CD Ware Multimedia 1995 May

home *** CD-ROM | disk | FTP | other *** search

/ CD Ware Multimedia 1995 May / cd Ware (Juegos) Epimundo.iso / DOS / C / DIALOG.ZIP / DBPRO1-@.COM / DBPRO.TXT < prev

Wrap

Text File | 1989-09-08 | 291.4 KB | 5,413 lines

The DialogPro * * * * * Users Guide and Reference Manual * * * * * by Kenneth Stott version 2.1 Seabreeze Software 908 Route 518 Skillman, New Jersey 08558 (609) 924-6793 Copyright (c) 1987-1989 by Kenneth Stott All Rights Reserved The DialogPro shareware diskette, containing a copy of this manual, may be freely copied and shared. But, printed copies of this document may not be copied by any method without the express written permission of Seabreeze Software. DialogPro v 2.1 Users Guide Reference Manual I. Introduction . . . . . . . . . . . . . . . . . . . . . 1 II. Overview . . . . . . . . . . . . . . . . . . . . . . . 3 III. Technical Notes . . . . . . . . . . . . . . . . . . . 6 IV. Shareware . . . . . . . . . . . . . . . . . . . . . . 12 V. Registration . . . . . . . . . . . . . . . . . . . . . 13 VI. Support Details . . . . . . . . . . . . . . . . . . . 15 VII. Diskette . . . . . . . . . . . . . . . . . . . . . . . 16 VIII. Installation . . . . . . . . . . . . . . . . . . . . . 18 IX. Compiling and linking the demo . . . . . . . . . . . . 19 X. DialogPro Reference . . . . . . . . . . . . . . . . . 20 A. Introduction . . . . . . . . . . . . . . . . . . . . . 20 B. Functions . . . . . . . . . . . . . . . . . . . . . . 21 1. db_display . . . . . . . . . . . . . . . . . . . . 21 2. db_displayq . . . . . . . . . . . . . . . . . . . 21 3. db_flushqueue . . . . . . . . . . . . . . . . . . 22 4. db_freestorage . . . . . . . . . . . . . . . . . . 22 5. db_pop . . . . . . . . . . . . . . . . . . . . . . 23 6. db_priority . . . . . . . . . . . . . . . . . . . 23 7. db_push . . . . . . . . . . . . . . . . . . . . . 23 8. db_restoreanswers . . . . . . . . . . . . . . . . 24 9. db_run . . . . . . . . . . . . . . . . . . . . . . 24 10. db_selectq . . . . . . . . . . . . . . . . . . . . 26 11. db_storeanswers . . . . . . . . . . . . . . . . . 27 12. db_switchqueue . . . . . . . . . . . . . . . . . . 28 13. lst_display . . . . . . . . . . . . . . . . . . . 29 14. lst_displayitem . . . . . . . . . . . . . . . . . 30 15. lst_freestorage . . . . . . . . . . . . . . . . . 31 16. lst_restoreanswers . . . . . . . . . . . . . . . . 31 17. lst_run . . . . . . . . . . . . . . . . . . . . . 32 18. lst_select . . . . . . . . . . . . . . . . . . . . 34 19. lst_storeanswers . . . . . . . . . . . . . . . . . 34 20. lst_toggle . . . . . . . . . . . . . . . . . . . . 35 C. Standard Return Values . . . . . . . . . . . . . . . . 36 D. Data structures . . . . . . . . . . . . . . . . . . . 37 1. button . . . . . . . . . . . . . . . . . . . . . . 37 2. db_colors . . . . . . . . . . . . . . . . . . . . 38 3. db_delimiters . . . . . . . . . . . . . . . . . . 39 4. dialog_box . . . . . . . . . . . . . . . . . . . . 40 5. free_form . . . . . . . . . . . . . . . . . . . . 43 6. list . . . . . . . . . . . . . . . . . . . . . . . 44 7. list_rec . . . . . . . . . . . . . . . . . . . . . 47 8. multi_choice . . . . . . . . . . . . . . . . . . . 50 9. rcbutton . . . . . . . . . . . . . . . . . . . . . 52 10. reducer . . . . . . . . . . . . . . . . . . . . . 53 11. scroll_txt . . . . . . . . . . . . . . . . . . . . 55 12. title . . . . . . . . . . . . . . . . . . . . . . 57 E. Global variables . . . . . . . . . . . . . . . . . . . 58 1. db_head, db_tail, db_queue . . . . . . . . . . . . 58 2. default_db_cmds . . . . . . . . . . . . . . . . . . 58 3. idle . . . . . . . . . . . . . . . . . . . . . . . 58 4. monitor_switch, _fg, _bg, _speed, _wdw, _tile . . . 58 5. mouse_sensitivity . . . . . . . . . . . . . . . . . 59 F. Messages . . . . . . . . . . . . . . . . . . . . . . . 60 1. Dialog Box . . . . . . . . . . . . . . . . . . . . 60 - 1 - DialogPro v 2.1 Users Guide Reference Manual 2. Line Editor . . . . . . . . . . . . . . . . . . . . 63 3. list question . . . . . . . . . . . . . . . . . . . 65 4. Pull down list . . . . . . . . . . . . . . . . . . 66 XI. Resource Files Reference . . . . . . . . . . . . . . . 67 A. Introduction . . . . . . . . . . . . . . . . . . . . . 67 B. Creating Resource Files . . . . . . . . . . . . . . . 67 1. Introduction . . . . . . . . . . . . . . . . . . . 67 2. ID record . . . . . . . . . . . . . . . . . . . . . 68 3. Window record . . . . . . . . . . . . . . . . . . . 68 4. Text Literal records . . . . . . . . . . . . . . . 69 5. Question records . . . . . . . . . . . . . . . . . 69 a. Introduction . . . . . . . . . . . . . . . . . . 69 b. Radio Button records . . . . . . . . . . . . . . 69 c. Checkbox records . . . . . . . . . . . . . . . . 70 d. Free Form records . . . . . . . . . . . . . . . 70 e. Button records . . . . . . . . . . . . . . . . . 71 f. List records . . . . . . . . . . . . . . . . . . 72 g. Multiple Choice records . . . . . . . . . . . . 72 h. Pulldown record . . . . . . . . . . . . . . . . 73 6. Terminator record . . . . . . . . . . . . . . . . . 73 C. Testing Resource Files . . . . . . . . . . . . . . . . 73 D. Incorporating Resource Files into your programs . . . 74 E. Embedding Resource Files . . . . . . . . . . . . . . . 76 F. Functions . . . . . . . . . . . . . . . . . . . . . . 77 1. create_db . . . . . . . . . . . . . . . . . . . . . 77 2. destroy_db . . . . . . . . . . . . . . . . . . . . 77 XII. HypeIt! . . . . . . . . . . . . . . . . . . . . . . . 78 - 2 - DialogPro v 2.1 Users Guide Reference Manual I. Introduction The DialogPro will help you implement one of today's hottest user interface analogies, the dialog box. The dialog box, popularized by Apple, is now a mainstay in almost all modern PC based software. And it is here to stay. Despite not being invented by IBM, it is included in their latest SAA user interface standards. If you don't already know, The dialog box is a pop-up window with a form inside of it. The form consists principally of questions, these questions can be checklists, multiple choice questions (sometimes known as radio buttons,) scrolling lists, and buttons. Buttons are special because they can indicate to perform some sort of action. Typically the action will be something like, confirm the answers to the other questions, or abort the dialog box (restore the old answers and return to the previous process.) The dialog box is a familiar sight to most personal computer users and is a tremendously simple way to get a solid, consistent, user interface into your applications. The bad news is that dialog boxes, while making life easier for the user, are difficult to implement. This is particularly true in a mouse environment -- where a user can literally click (or point, or press, or drag, etc., etc.) on any thing he sees on the screen -- how do you deal with that in a traditional structured programming style? The answer is you don't have to, at least not directly. Most programmers work in a competitive, cost conscious environment and don't have the time to ponder messaging and object orientation. The DialogPro lets you use the latest techniques, without sweating the details. It lets you put the latest, most professional, Microsoftish/Borlandish/Macontish interface on your programs without the pain. Your users will be able to hang onto to their mice and learn your programs faster (even if you don't get it -- A lot people have fallen in love with the mouse.) And you'll be relieved of a big part of the programming, the training, and the support. The DialogPro is tremendously flexible. Every dialog box understands over 60 commands -- you program these commands to any keystrokes you like. Create additional commands, hot-keys, etc. by defining macro-commands and attaching them to keystrokes. Automatically update target variables in your applications. "Hook" in your own routines directly into dialog box questions. Perform edit checking and field updating/formatting on the fly, anything you can imagine. There are just so many uses for the DialogPro that it is hard to list them all here. But things like interreferenced help systems a la Lotus 1-2-3 are pretty straight forward. Likewise, creating a user interface that conforms to SAA standards would be easy. The DialogPro is perfect for desktop oriented applications because at the heart of the DialogPro are sophisticated, - 1 - DialogPro v 2.1 Users Guide Reference Manual object-oriented, messaging algorithms. But the DialogPro is just as comfortable sprucing up existing programs because the sophistication is literally "at the heart" of The DialogPro; ready to be put to use when you need it--but ingeniously "hidden" until you want it. And that really is the key to The DialogPro--it gives you what YOU want, adapts to your style. - 2 - DialogPro v 2.1 Users Guide Reference Manual II. Overview The user sees a dialog box like this. A form to fill in. A dynamic form where lists can scroll, amounts fill in automatically, and buttons can be pushed to continue or perform other actions. +[ Personal Information ]-----------------+ | | | Name : _________________________________ | | Street : _______________________________ | | City : _________________________________ | | State : __ Zip Code __________________ | | | | Occupation : +----------------------+ | | |[ ] Doctor ^^ | | +=========+ |[ ] Dentist || | | | Confirm | |[ ] Lawyer || | | +=========+ |[ ] Accountant oo | | +---------+ |[ ] Mechanic || | | | Abort | |[ ] Engineer vv | | +---------+ +----------------------- | +-------------------------------------------+ The programmer sees this as a hierarchical data structure. The dialog box is a structure with a series of subordinate data structures representing the various questions, buttons, and lists. As the programmer your principal task is to create these data structures. The db_run and db_display functions are then used to execute and/or display the dialog boxes. In the above example your would first define a dialog box structure. You would then define free_form (or fill-in-the-blank) structures for the Name, Street, City, and Zip Code fields. The State field could be represented as either a multiple choice question, a reduction question (where the user supplies part of the answer and the dialog box attempts to determine the correct answer or displays a list of possible answers to select from -- like all the states that begin with M, for example,) or it could be just another fill in the blank question. Confirm and Abort would be defined as button structures and Occupation would be a list structure. To see an example of how to create a simple dialog box see the included source file, SIMPLEDB.C. Of course, if this were the end of the story The DialogPro wouldn't be all that useful. There are several default data types to help you get started but ultimately the programmer has final control over virtually every aspect of how a dialog box looks and operates. For example, - 3 - DialogPro v 2.1 Users Guide Reference Manual . You can position questions anywhere in the pop-up window, or in separate tiles of a pop up window, even create paged dialog boxes by swapping tiles in and out. . You can control how the questions are presented to the user. Including delimiter characters, the position of the statement describing the question, where the response to the question should be located, the maximum length of the response, the color of the statement, the color of the response, and many more aspects. . You may assign target variables to questions. Target variables are automatically updated with the responses to questions as they are answered. . You can control the order that the user navigates to the questions. . You can "hook" in pre and/or post routines to each question. Using the pre/post routines you can do edit checking, field updating, even modify the user interface. . You can indicate that questions are "unavailable" for modification. In a graphics environment this is sometimes known as "greying" out a choice. . You can extend both the mouse and keyboard interface by creating macros to define completely new commands and features, or combine or modify existing features. Macros can call your own routines or simply expand into a series of alternative messages. This feature alone makes the DialogPro almost infinitely extendable. Resource Files Fairly complex dialog boxes can be defined using dialog box resource files. You can define one or more dialog boxes in a resource file and then instruct DialogPro to create a dialog box, display or run the created dialog box, and to destroy the dialog box. The DialogPro allows resource files to be embedded in other files. For example, you can append your resource files to your executable file to make user install procedures simpler, to control the files better, etc. Resource files are the simplest way to get access to the DialogPro. Authoring programs are included to help you create and test resource files. See the "Using Resource Files" manual for more information on resource files. HypeIt! - 4 - DialogPro v 2.1 Users Guide Reference Manual A hypertext library (hypeit) is included. HypeIt! is a help engine that lets you incorporate hypertext like help systems into your programs. It also includes authoring programs to help you build, test, or distribute hyperdocs. Run the program hypeit.exe for more information on using the hypeit libs. - 5 - DialogPro v 2.1 Users Guide Reference Manual III. Technical Notes This section describes what you'll need to use The DialogPro, any limitations you should be aware of, and describes (in further detail) the theory of operation. The WindowPro The DialogPro is based on The WindowPro. You must have The WindowPro to use The DialogPro. Just like The DialogPro, The WindowPro is also available from Seabreeze Software. If you have The WindowPro, and it works on your machine and compiler, then so will The DialogPro. (Note: The DialogPro is currently only tested with Quick-C 1.X, MSC C 5.X, and Turbo C 1.X compilers.) Size The DialogPro adds about 45K of code to your application, in addition to requiring virtually the full WindowPro library (which adds about another 60K.) What is a dialog box? Dialog boxes and questions are hierarchical data structures. Each dialog box routine operates on a given data structure. Because they are data structures you can modify them, on the fly. In fact your pre/post routines can "grey-out" options, update fields, and remove questions dynamically by doing just that. The dialog box routines interpret the data structures to display the dialog box, select methods of dealing with user commands, etc. As such, the application programmers main task is to "fill-in" these data structures properly. Messages at first glance The major dialog box routine is db_run. db_run handles the bulk of the work, interpreting all messages and parceling out the work to the lower level routines. They each have their own keyboard and mouse handlers so that they operate as closed systems or black boxes. You call the routines, they execute, put the results into the target variables, and return to the calling function. The application programmer doesn't deal with message queues, keyboards, or mice--A BLACK BOX. But inside the black box keyboard and mouse handlers interpret keyboard and mouse activity into messages. The messages are then placed into a queue and processed. Despite being somewhat - 6 - DialogPro v 2.1 Users Guide Reference Manual "invisible" the capability to manipulate the message queues is there. Manipulating messages directly can give you added flexibility. Using the KEYBOARD Each of the messages recognized by a dialog box (see DBOPS.H for a complete list) can be associated with a keyboard code (a scan code & ascii code two byte sequence.) This keyboard interface is represented as an array of integers where its position in the array relates to the message value. Any keystroke can be assigned to any message. The keyboard handler uses this lookup table to redefine keystrokes into the messages which db_run processes. Using the MOUSE The mouse handler routines generate messages in the same way that the keyboard handler generates dialog box messages. Although there is no lookup table to help you redefine the mouse interface. You can define macros which intercept the mouse generated messages and redefine them. Creating and Interpreting Messages Each data structure has an associated function to interpret messages. Each of these functions handles messages like this. 1. It takes the message passed as a parameter and puts it at the head of the current circular queue. 2. It looks for a message at the tail of the queue. A. If a message is found: a. It first looks up the message in the macro list. If the message is a macro it expands the macro by putting the new messages at the tail of the queue, and then returns to step 2, b. Messages must have a value of less than 256. If the message has a value of greater than 256 we assume that it is an extended keyboard code. The extended kyeboard code is intepreted into a "real" message". The "real" message is placed at the tail of the queue, and it then returns to step 2. - 7 - DialogPro v 2.1 Users Guide Reference Manual c. If we make it past steps 2.A.a and 2.A.b we execute the message. The CONFIRM, ABORT, SPECIAL messages terminate db_run and return back to the calling function. If the message is not one of the above it returns to step 2 to get another message to execute. C. If no message is found, it polls the mouse and the keyboard waiting for activity. If activity is found, the activity is interpreted into a message and put at the tail of the queue -- it then returns to step 2. You can modify the behavior of The DialogPro by manipulating the message queues. Several functions are provided for putting messages at the head and the tail, and for reading the message queue. More Notes on Working with Dialog Boxes and Messages The term 'question' is roughly equivalent to the term 'control' in MS-Windows. 'questions' are the elements which comprise a dialog box. At any time any question within the dialog box may have control of the queue (in MS-Windows this is similar to having the focus.) A question relinquishes control of the queue on receiving an ASCEND, DESCEND, CONFIRM, ABORT, NEXT, or PREV message. Remember that the Dialog Pro sees everything as hierarchical structures, with this in mind, the ASCEND message gives control of the queue to the superior object, usually a dialog box. A DESCEND message gives control of the queue to the current questions subordinate object, for example in a multiple choice question this would display a pull down list and the pull down list would then control the queue. The DialogPro is similar to object oriented programming except that 'unknown' messages are discarded instead of being implicitly passed to the superior class for processing. However, messages can be, and frequently are, passed to superior objects explicitly. The basic technique for passing a message to a superior object is to push an ASCEND and then the original message back onto the queue. The ASCEND forces the current object to relinquish control of the queue to the superior object. The next message on the queue which the superior object now receives is the original message. For example, if NEXT or PREV is received in a free_form question it responds by pushing an ASCEND and a NEXT or PREV) onto the queue. The ASCEND is then taken from the queue. This results in - 8 - DialogPro v 2.1 Users Guide Reference Manual control of the queue passing to the dialog box. The dialog box takes the NEXT from the queue and handles it by selecting the next question. The best way to see how messages are processed is to use the queue monitor when creating and debugging a dialog box. The Questions FREE_FORM Free form questions are used to gather one line text responses. The text can be up to a thousand characters long. The response area can be any size. While editing, the response text scrolls within the response area. The line editor has home, end, word right/left, and character right/left, backspace and delete functions. Clicking on any character places the cursor on the character. MULTI_CHOICE Multiple choice questions can be configured to operate as pull down menus or as more traditional multiple choice questions. The principle difference is that the current response to a multiple choice question is displayed in the response area. The pulldown menu type doesn't display the current response. The user cycles through the responses to a multiple choice question with PRESS_BUTTON, or selects the next response beginning with a specific character, or pulls down the list of available choices with the DESCEND or EXPAND commands -- and then selects his choice from the complete list. With the mouse, the user cycles through the available responses by clicking on the response area. He pulls down the list of available responses by double-clicking, or holding, on the response area. RADIO BUTTONS Radio buttons serve the same purpose as multiple choice questions, except that all of your available choices are displayed in the dialog box rather than just your currently selected choice. CHECKBOXES Checkboxes let you toggle an item on and off. REDUCER - 9 - DialogPro v 2.1 Users Guide Reference Manual Reducer questions operate just like free_form except that after confirming DialogPro compares the response to a list of available responses. If there is only one response which matches the current response -- nothing happens. If more than one available response begin with the same letters as the given response, the response is considered ambiguous and a list of possible matches is displayed in a pulldown list. The user then selects his response from the pulldown list. The user can skip the reduction stage and go straight to the list by pressing EXPAND. The user can view the entire list by double-clicking or holding on the response area with the mouse. LIST There are two types of lists, select list and checklist. The checklist allows more than one item to be "checked-off." he select list allows only one item at a time to be "checked-off." A list response area is rectangular. If the list is bigger than the rectangular area the user can scroll the list. The user can modify the selections by placing the cursor inside the list. The user can then check-off items using PRESS_BUTTON or navigate to another question. With the mouse, clicking on an item in the list will toggle it between checked and un-checked. Holding or clicking on the scroll bar hotpoints, or holding and dragging the scroll bar thumbwheels scroll the list. BUTTON The user executes a button by pressing the key it is "bound" to. Pressing the "bound" key will place the button's command key in the message queue. This lets buttons behave as another way of executing a CONFIRM, or ABORT, or any command -- or keystroke. A kind of visual representation of commands. You can also execute a button by pressing its mnemonic key. Its mnemonic key will first make the button the selected question and then put the command key in the message queue. The basic difference is that the first method does not change the selected question, or highlighting. This method changes the highlighted item to the button. You can also execute a button by navigating to it (or highlighting it) and then executing PRESS_BUTTON. - 10 - DialogPro v 2.1 Users Guide Reference Manual With the mouse, clicking on a button is the same as pressing the "bound" key. Holding on a button and then releasing it the same as pressing the mnemonic key. Buttons may or may not have a border. Buttons without borders are useful for making words in a text behave like hot-points (useful in hypertext type applications, help screens, etc.) or in creating new hot-points that work like the scroll bars, for example, creating a sliding scale in a dialog box would be done with borderless buttons representing different parts of the scale (an up button, a down button, the scale itself, etc. -- this lets users literally reach out and grab a piece of your invention and move it around the screen, pull levers, push buttons, and move sliding scales.) SCROLLING TEXT Scrolling text questions is really a misnomer. Scrolling text allows you to place a sub-window within the dialog box and then associate a controlling routine with that sub-window. Some of the common uses for this would be, for example, a box of scrolling text, or a sub-dialog box. Sample control routines for both of these types of SCROLLING TEXT questions are included. But, you can create your own routines, infinitely extending the abilities of The DialogPro. - 11 - DialogPro v 2.1 Users Guide Reference Manual IV. Shareware Seabreeze Software distributes DialogPro under the shareware marketing concept. Because DialogPro is shareware you can freely copy and share the DialogPro shareware diskette with its programs and manual. You can also obtain it from Seabreeze Software for $15 (the cost of the diskette, postage, and handling.) In fact, we hope you do help us by sharing unmodified copies of the DialogPro shareware diskette with other programmers. You may incorporate DialogPro into your programs and distribute those programs absolutely royalty free (see registration section for details.) You may not however sell, or give away, the DialogPro source code -- even if you purchase the right to use it (see registration section.) - 12 - DialogPro v 2.1 Users Guide Reference Manual V. Registration Shareware is software which can be freely copied and distributed. It is copyrighted software which the author encourages people to copy and share with others. You can register with Seabreeze Software for three levels of support: . For $50 you receive . A serialized diskette containing all the latest libraries for all supported compilers and memory models. . Single user telephone support (BBS, Compuserve, and voice.) See next section for details. . Notification of updates for one year. . For $100 you receive . the above, and . one hundred pages of liberally commented source code (on diskette,) This support-level is usable for non-commercial programs. Non-commercial programs are those created for limited user (less than 50 users) installations (as typically might be found in a small consulting situation or a small corporate software development setting,) or for unlimited shareware or freeware distribution. . For $200 you receive . the above, plus . the right to use DialogPro in commercial applications. . Call for details regarding site licensing, consulting services, and customizations. Seabreeze Software retains the following rights: . If you purchase the source code you may not distribute it except as part of an application program. In other words, you can't resell the source in its current or modified form in a way that competes with the original product. . If you provide the DialogPro source code to a purchaser of your applications software you must leave the remarks in the source code indicating that the original copyright is held by Seabreeze Software. If you rewrite portions of DialogPro you - 13 - DialogPro v 2.1 Users Guide Reference Manual must point out the modifications made by yourself and you are legally obligated to leave the original copyright notice in the source code. . Seabreeze Software may modify its pricing and distribution policies at any time without notification. This does not imply that we will not honor our contractual obligations. But that we reserve the right to not contract for the above services at the above prices, i.e. we are not bound by 'old' advertising. The registration form is at the back of this manual. - 14 - DialogPro v 2.1 Users Guide Reference Manual VI. Support Details Support is provided by . E-mail. Send mail to Seabreeze Software, Compuserve ID# 72330, 705 . Voice. You may call Seabreeze Software directly at 609-924-6793, Monday through Friday, 9 a.m. to 5 p.m. Eastern Time. Technical support is available to registered users only, you must leave your license agreement number, your name, and instructions for answering the question (like - "please answer via Compuserve E-mail ID# XXXXX, XXX." or "Please call me at XXX-XXX-XXXX for verbal consultation.") Give as many details as possible. Answers will generally be received within 24 hours or less, Monday through Friday. Seabreeze Software will respond to general questions from unregistered users, like "I have version X.XX, what is the latest version?" or "What is the current price for support level X?" We cannot respond to technical questions from unregistered users. - 15 - DialogPro v 2.1 Users Guide Reference Manual VII. Diskette The shareware diskettes should contain the following files: READ.ME Any last minute corrections, additions, etc. PKXARC.COM Unarchives Pro.arc DBPRO1.ARC This manual and demo exe files DBPRO2.ARC Required include, batch, and source files DBPRO3.ARC Microsoft MS C/Quick-C libraries DBPRO4.ARC Turbo-C libraries DBPRO5.ARC Quick-C quicklib dbpro1.arc, dbpro2.arc, dbpro3.arc, dbpro4.arc & dbpro5.arc contain: DBPRO.TXT Users guide and reference manual for The DialogPro DBCHANGE.TXT Summary of changes between various DialogPro versions. MSDBPROM.LIB DialogPro MS C 5.X / Quick C 1.X medium model library MSDBPROL.LIB DialogPro MS C 5.X / Quick C 1.X large model library QCDBPRO.C This file is a "stub" function that references all DialogPro functions. It allows you to create a Quick-C 1.X quicklib. See your Quick-C manual for further information. TCDBPROM.LIB DialogPro Turbo C medium model library TCDBPROL.LIB DialogPro Turbo C large model library DBERRORS.H DialogPro include files DBOPS.H " DBPRO.H " SIMPLEDB.C Easy example of a simple dialog box SIMPLEDB.PRJ Turbo-C project file for above sample program. CLONE.C Another sample dialog box & Turbo-C project file. CLONE.PRJ QCDBPROM.BAT Generic Quick C medium model DialogPro compile/link batch file QCDBPROL.BAT Generic Quick C large model DialogPro compile/link batch file MSDBPROM.BAT Generic MS C medium model DialogPro compile/link batch file MSDBPROL.BAT Generic MS C large model DialogPro compile/link batch file TCDBPROM.BAT Generic Turbo C medium model DialogPro compile/link batch file TCDBPROL.BAT Generic Turbo C large model DialogPro compile/link batch file DBTEST.EXE DialogPro resource file test program IDXTEST.EXE Resource file indexer TEST.RSC Sample resource file - 16 - DialogPro v 2.1 Users Guide Reference Manual TEST.IDX " " index DEMO.BAT Resource file demo HYPEITLM.LIB MS C 5.X HypeIt! large model lib HYPEITLT.LIB Turbo-C 2.X Hypeit! large model lib HYPEIT.EXE HypeIt! document previewer HYPEIT.TXT HypeIt! documentation file (a hyperdoc) HYPEIT.IDX HypeIt! documentation file index COLRLIST.EXE HypeIt! color codes program Note: BBS operators may repackage The DialogPro files to optimize on-line time. If you received your files via a BBS please make sure you have all of The DialogPro shareware files. - 17 - DialogPro v 2.1 Users Guide Reference Manual VIII. Installation 1. Backup your shareware diskette. 2. Type "pkxarc dbpro1" at the dos prompt and press ENTER, and then "pkxarc dbpro2". Pkxarc will unarc dbpro1.arc & dbpro2.arc into the current default directory. You can run pkxarc.exe from another directory, and unarc dbpro1.arc located on another drive or directory by preceding each with a drive and directory specification, for example C:\Pro>a:pkxarc a:dbpro1 will run pkxarc from the a: drive and unarc dbpro1.arc located on the a: drive into the c: drive and the "Pro" sub-directory. Repeat for dbpro3.arc and dbpro4.arc. 3. Copy the library files for your compiler (extension of ".lib") to the diskette or sub-directory you usually use with your C compiler. The lib files should be in the same sub-directory as your C runtime libraries. - 18 - DialogPro v 2.1 Users Guide Reference Manual IX. Compiling and linking the demo Confirm proper installation by compiling one of the demo programs, simpledb.c by typing the following (choose the one that corresponds to your compiler and memory model.) msdbprol simpledb msdbprom simpledb qcdbprol simpledb qcdbprom simpledb tcdbprol simpledb tcdbprom simpledb If you were unable to compile and link check to make sure that: TURBO-C : Determine that you have all of the files listed on the previous page. Turbo-C is installed as described in the Turbo-C manual, you are compiling from the TURBOC directory, the source files are in the default sub-directory, and the TCDBPRO?.LIB files are installed in the LIB sub-directory. QUICK-C : Determine that the LIB, TMP, BIN, and INCLUDE environment variables have been properly initialized, the MSDBPRO?.LIB files are included in the subdirectory associated with LIB environment variable, and the source files are in your default directory. If the problem persists contact Seabreeze Software Customer Support. - 19 - DialogPro v 2.1 Users Guide Reference Manual X. DialogPro Reference A. Introduction Generally speaking you only need to be familiar with the functions db_run, lst_run, db_switchqueue, and the data structures dialog_box and list_rec. All of the other functions are documented solely to assist the application programmer in writing pre and post routines to attach to questions. Using these functions can help you do things like modify the dialog_box structure based on an interim response. Typically this technique is used to gray-out a questions in a dialog box based on another response or to perform other similar processes. The DialogPro is targeted for experienced applications developers. The best way to learn how to use the DialogPro is by studying, running, and modifying the sample programs. - 20 - DialogPro v 2.1 Users Guide Reference Manual B. Functions 1. db_display a. Summary #include "dbpro.h" #include "dbpro.h" int db_display(db_ptr) ______ i ) ______ dialog_box *db_ptr; _______ dialog_box * _______ b. Description Displays the dialog box pointed to by dp_ptr. If the window ________ associated with db_ptr is not on the screen it will be opened via ______ a call to wn_openw. If the window associated with the dialog box wn_openw (db_ptr->handle) is open but is not the last_wdw (on top of the ______ ->handle last_wdw ______ stack of windows) and db_ptr->bg_operation is TRUE it will be ______ ->bg_operation ______ brought to the top of the stack by a call to wn_openw. wn_openw c. Return Value See section Standard Return Values. 2. db_displayq a. Summary #include "dbpro.h" #include "dbpro.h" int db_displayq(db_ptr, question_id) ______ ___________ int db_displayq( , ) ______ ___________ dialog_box *db_ptr; _______ dialog_box * _______ unsigned char question_id; ____________ unsigned char ____________ b. Description Displays the question pointed to by db_ptr->questions[question_id] in the window db_ptr->handle. ______ ___________ ______ ->questions[ ] ->handle ______ ___________ ______ c. Return Value See section Standard Return Values. - 21 - DialogPro v 2.1 Users Guide Reference Manual 3. db_flushqueue a. Summary #include "dbpro.h" #include "dbpro.h" void db_flushqueue(void) ____ void db flushqueue ____ b. Description Clears all messages in the queue, db_queue. Indiscriminate use db queue of db_flushqueue() is not advised. It may interfere with the processing of macros. It is best to discard only those messages which you are sure you do not want. c. Return Value None. 4. db_freestorage a. Summary #include "dbpro.h" #include "dbpro.h" int db_freestorage(db_ptr, insurance) ______ _________ int db_freestorage( , ) ______ _________ dialog_box *db_ptr; _______ dialog_box * _______ storage **insurance; __________ storage ** __________ b. Description If *insurance does not equal NULL the data structure pointed to __________ NULL __________ by *insurance is freed and *insurance is set to NULL. __________ __________ NULL __________ __________ If *insurance is equal to NULL, nothing happens. __________ NULL __________ (Normally **insurance is the same as &(db_ptr->insurance). ___________ ______ &( ->insurance) ___________ ______ db_ptr->insurance is used by db_run to point to the previous ______ ->insurance db_run ______ answers to the dialog box.) c. Return Value See section Standard Return Values. - 22 - DialogPro v 2.1 Users Guide Reference Manual 5. db_pop a. Summary #include "dbpro.h" #include "dbpro.h" unsigned db_pop(void) ____ unsigned db pop ____ b. Description Reads the next message from the tail of the queue, db_queue. db queue c. Return Value <> - 1 Function executed properly. -1 The queue is empty. 6. db_priority a. Summary #include "dbpro.h" #include "dbpro.h" int db_priority(new_event) ___ _____ int db priority ___ _____ unsigned new_event; ___ _____ unsigned ___ _____ b. Description Puts new_message at the tail of the queue, db_queue. ___ _______ db queue ___ _______ c. Return Value TRUE Function executed properly. TRUE FALSE The queue is full (a queue can only have 256 messages FALSE in it.) 7. db_push a. Summary #include "dbpro.h" #include "dbpro.h" int db_push(new_event) ___ _____ int db push ___ _____ unsigned new_event; ___ _____ unsigned ___ _____ - 23 - DialogPro v 2.1 Users Guide Reference Manual b. Description Puts new_message at the head of the queue, db_queue. ___ _______ db queue ___ _______ c. Return Value TRUE Function executed properly. TRUE FALSE The queue is full (a queue can only have 256 messages FALSE in it.) 8. db_restoreanswers a. Summary #include "dbpro.h" #include "dbpro.h" int db_restoreanswers(db_ptr, insurance) ______ _________ int db_restoreanswers( , ) ______ _________ dialog_box *db_ptr; _______ dialog_box * _______ storage **insurance; __________ storage ** __________ b. Description If *insurance is not equal to NULL the answers to the dialog box, __________ NULL __________ db_ptr, are changed to the answers recorded in the data structure ______ (which only contains the answers) of type storage pointed to by storage *insurance. The storage data structure is freed and *insurance __________ storage __________ is set to NULL. NULL If insurance is equal to NULL, nothing happens. _________ NULL _________ (Normally **insurance is the same as &(db_ptr->insurance). ___________ ______ &( ->insurance) ___________ ______ db_ptr->insurance is used by db_run to point to the previous ______ ->insurance db_run ______ answers to the dialog box.) c. Return Value See section Standard Return Values. 9. db_run a. Summary #include "dbpro.h" #include "dbpro.h" int db_run(db_ptr, message) ______ _______ int db_run( , message) ______ _______ dialog_box *db_ptr; _______ dialog_box * _______ - 24 - DialogPro v 2.1 Users Guide Reference Manual unsigned message; ________ unsigned ________ b. Description The function db_run executes the messages in the message queue db_run pointed to by db_queue against the dialog box data structure db_queue db_ptr. (It is very important that a message queue have been ______ initialized via a call to db_switchqueue before calling db_run.) db switchqueue db run Before executing the message queue it first places the standard message STORAGE at the tail of the queue and then it places the STORAGE parameter message at the head of the queue. All messages are _______ retrieved from the tail of the queue. Each retrieved message is checked against the macro list db_ptr->macros. If the message is ______ ->macros ______ a macro it is expanded by placing the items pointed to by the macro at the tail of the queue in reverse order. If there are no messages in the message queue db_run polls the db_run kyeboard and mouse (if one is recognized when wn_init is called.) When activity is noted the keyboard/mouse activity is translated into a message and placed at the tail of the queue. If it is a mouse event the message MOUSE_EVENT is placed at the MOUSE_EVENT tail of the queue. The MOUSE_EVENT message takes the last mouse MOUSE_EVENT event, translates it into a message and places it at the tail of the queue. It it is a keyboard event, the keystroke is first compared against the the shortcut key of each of the questions, starting at the current question + 1 and ending at the current question. The first question whose shortcut key matches the keystroke is selected. If the question is a button and it matches BUTTONQUEST(question_id)->key the button is selected, the BUTTONQUEST(question_id)->key keystroke value is replaced with the value BUTTONQUEST(question_id)->cmd_key, and the global variable BUTTONQUEST(question_id)->cmd_key button_press is set the the value of button_press BUTTONQUEST(question_id)->exitval. If the question is a button BUTTONQUEST(question_id)->exitval and it matches BUTTONQUEST(question_id)->keybind the current BUTTONQUEST(question_id)->keybind question remains selected, and the keystroke value is replaced with the value BUTTONQUEST(question_id)->cmd_key, and the global BUTTONQUEST(question_id)->cmd_key variable button_press is set the the value of BUTTONQUEST(question_id)->exitval. BUTTONQUEST(question_id)->exitval The new keystroke value is then compared against the keystroke-command table. If the keystroke is in the table the keystroke is interpreted into a standard event. If it is not, it is processed as a keystroke value. Alphanumeric Keystrokes can be used to begin editing a free_form, a reducer, or select a multiple choice response. When one of several exit type messages is received db_run terminates. - 25 - DialogPro v 2.1 Users Guide Reference Manual The actual message selection/interpretation code explains it a little more succinctly: do { /* get event from queue */ if (!NO_EVENT) event = db_pop(); /* or from keyboard/mouse */ else event = get_dbevent(db_ptr); } while /* expand macros */ (db_executemacros(event, db_ptr->macros)); /* if event is a keystroke value ... */ if (event > 256) { /* get ascii code */ ascii = event % 256; /* check shortcut keys */ button_press = db_touchbutton(db_ptr, &event); /* translate into a message */ event = db_getopcode(db_ptr, event); } c. Return Value See section Standard Return Values. Note that if this function returns with a value of CONFIRMED or ABORTED that it has also placed a CONFIRM or ABORT message in the queue. Many programmers find that using the queue for sending and receiving arguments and return values is the cleanest way to use the DialogPro. On the other hand, particularly if you are integrating the DialogPro into an existing application you may want to discard these messages. Use db_pop() to discard the unwanted message, or db_flushqueue() to discard all messages in the queue. 10. db_selectq a. Summary #include "dbpro.h" #include "dbpro.h" - 26 - DialogPro v 2.1 Users Guide Reference Manual int db_selectq(db_ptr, question_id) ______ ___________ int db_selectq( , ) ______ ___________ dialog_box *db_ptr; _______ dialog_box * _______ unsigned char question_id; ____________ unsigned char ____________ b. Description Makes db_ptr->id_select equal to question_id. Then displays the question pointed to previously by db_ptr->questions[db_ptr->id_select] (dehighlighting the question) and then displays the question db_ptr->questions[question_id] (highlighting it--as it is now the ______ ___________ ->questions[ ] ______ ___________ selected question.) Before dehighlighting the first question, the function pointed to by (*) FIRST_QUESTION->whenoff(db_ptr) is executed, if FIRST_QUESTION->whenoff(db_ptr) does not return TRUE db_selectq terminates without modifying db_ptr->id_select. After dehighlighting the second question, the function pointed to by (*) SECOND_QUESTION->whenon(db_ptr) is executed, if SECOND_QUESTION->whenon(db_ptr) does not return TRUE db_selectq terminates without modifying db_ptr->id_select. (*) FIRST_QUESTION and SECOND_QUESTION are generic pointers use for illustrative purposes representing what would be the specific pointer type for each question. Each question type has its own pointer type. c. Return Value See section Standard Return Values. 11. db_storeanswers a. Summary #include "dbpro.h" #include "dbpro.h" int db_storeanswers(db_ptr, insurance) ______ _________ int db_storeanswers( , ) ______ _________ dialog_box *db_ptr; _______ dialog_box * _______ storage **insurance; __________ storage ** __________ - 27 - DialogPro v 2.1 Users Guide Reference Manual b. Description If *insurance is equal to NULL the answers to the dialog box, __________ NULL __________ db_ptr, are stored in an interim data structure (which only ______ contains the answers) of type storage and *insurance returns the __________ storage __________ pointer to the data structure. If insurance is not equal to NULL, nothing happens. _________ NULL _________ (Normally **insurance is the same as &(db_ptr->insurance). ___________ ______ &( ->insurance) ___________ ______ db_ptr->insurance is used by db_run to point to the previous ______ ->insurance db_run ______ answers to the dialog box.) c. Return Value See section Standard Return Values. 12. db_switchqueue a. Summary #include "dbpro.h" #include "dbpro.h" int db_switchqueue(head, tail, queue) ____ ____ _____ int db switchqueue ____ ____ _____ unsigned char *head, *tail; ____ ____ unsigned char ____ ____ unsigned *queue; _____ unsigned _____ b. Description db_switchqueue associates variables representing the head, tail, db switchqueue and circular message queue used by db_run and lst_run. This db run lst run function must be called once before using db_run or lst_run. It db run lst run only has to be called once and then db_run and lst_run can be db run lst run used as many times necessary. You can however call this more than once if you want to use separate message queues for different dialog boxes. queue must be a pointer to a 512 byte memory block (256 _____ integers.) head and tail should be pointers to existing unsigned ____ ____ chars. head and tail should be initialized to their proper ____ ____ values before calling db_switchqueue. If you are just db switchqueue initializing a brand new queue both would be 0. c. Return Value None. - 28 - DialogPro v 2.1 Users Guide Reference Manual 13. lst_display a. Summary #include "dbpro.h" #include "dbpro.h" int lst_display(list_ptr, mode) ________ ____ int lst_display ________ ____ list_rec *list_ptr; ________ list_rec * ________ unsigned char mode; ____ unsigned char ____ b. Description Refreshes the display of the list, list_ptr. ________ If mode is equal to ____ 0 The window, lst_ptr->handle, is brought to the top of ________ ______ lst_ptr ________ ______ the stack of windows via a call to wn_openw. wn_openw 1 The window, lst_ptr->handle, is brought to the top of ______ lst ptr- ______ the stack of windows via a call to q_open. q_open is q open q open faster than wn_openw but no windowing functions which wn openw disrupt the order of display (wn_closew, wn_openw, or wn closew wn openw wn_activew) should be called without first removing the wn activew window by a call to q_close. This mode is used in pull q close down menus for example because it is designed in a way that makes certain that the window is closed on exit. 2 Only the virtual screen is refreshed. The changes are not updated on the physical screen. These data structures members may be effected by lst_display (Note: in the following listing TILE is defined as TILE window[lst_ptr->handle]->tiles[lst_ptr->tile_handle] and WDW is ___ ____ ___ ____ window handle tiles tile handle WDW ___ ____ ___ ____ defined as window[lst_ptr->handle]): ___ ____ window handle ___ ____ lst_ptr->optlen The length of the longest string in ___ ____ optlen ___ ____ the list of options. lst_ptr->taglen The length of the longest on/off ___ ____ taglen ___ ____ tag (displayed to the left of each option in the list. lst_ptr->numopts The number of options in the list. ___ ____ numopts ___ ____ TILE->virtual_screen If (TILE->vs_rows * TILE- virtual screen TILE- vs rows TILE->vs_columns) > TILE- vs columns (lst_ptr->numopts * ___ ____ numopts ___ ____ (lst_ptr->taglen + ___ ____ taglen ___ ____ lst_ptr->optlen)) then ___ ____ optlen ___ ____ TILE->virtual_screen is deallocated TILE- virtual screen - 29 - DialogPro v 2.1 Users Guide Reference Manual and a larger memory block is allocated. TILE->virtual_screen TILE- virtual screen then points to the new memory block. TILE->vs_rows, TILE- vs rows TILE->vs_columns If TILE->vs_rows does not equal TILE- vs columns TILE- vs rows lst_ptr->numopts or ___ ____ numopts ___ ____ TILE->vs_columns does not equal TILE- vs columns (lst_ptr->optlen + lst_ptr->taglen) ___ ____ ___ ____ optlen taglen ___ ____ ___ ____ then TILE->vs_columns is set equal TILE- vs columns to lst_ptr->optlen + ___ ____ optlen ___ ____ lst_ptr->taglen and TILE->vs_rows ___ ____ taglen TILE- vs rows ___ ____ is calculated based on the size of the memory block pointed to by TILE->virtual_screen. TILE- virtual screen WDW->port_columns If lst_ptr->auto_horiz is TRUE and ___ ____ WDW- port columns auto horiz TRUE ___ ____ lst_ptr->optlen + lst_ptr->taglen ___ ____ ___ ____ optlen taglen ___ ____ ___ ____ does not equal WDW->port_columns, WDW- port columns WDW->port_columns is set equal to WDW- port columns lst_ptr->optlen + lst_ptr->taglen. ___ ____ ___ ____ optlen taglen ___ ____ ___ ____ WDW->port_rows If lst_ptr->auto_vert is TRUE and ___ ____ WDW- port rows auto vert TRUE ___ ____ lst_ptr->numopts does not equal ___ ____ numopts ___ ____ WDW->port_rows, WDW->port_rows is WDW- port rows WDW- port rows set equal to lst_ptr->numopts. ___ ____ numopts ___ ____ If the list is not changed this function operates quickly. If the list is larger than the previous list lst_display must free lst display the original virtual screen and allocate memory for the new virtual screen. This can make for a small hiccup when opening a modified list. You can get around this hiccup by calling lst_display with mode equal to 0 after modifying the list at a point where processing speed is less critical. When lst_display lst display is called (probably via lst_run) for actual display the user will lst run not notice any delay. c. Return Value See section Standard Return Values. 14. lst_displayitem a. Summary #include "dbpro.h" #include "dbpro.h" int lst_displayitem(list_ptr, offset) ________ ______ int lst_displayitem ________ ______ list_rec *list_ptr; ________ list_rec * ________ - 30 - DialogPro v 2.1 Users Guide Reference Manual int offset; ______ int ______ b. Description Refreshes the display of the offset item (the first item is 0) in ______ the list list_ptr. ________ If offset is greater than the number of items in the list ______ (list_ptr->numopts) then a blank line is output at that row in _________ ->numopts _________ the virtual screen. If offset is greater than the last row in the virtual screen ______ an OUT_OF_RANGE error is returned. OUT_OF_RANGE c. Return Value See section Standard Return Values. 15. lst_freestorage a. Summary #include "dbpro.h" #include "dbpro.h" int lst_freestorage(insurance) _________ int lst_freestorage( ) _________ lst_storage **insurance; __________ lst_storage ** __________ b. Description If *insurance does not equal NULL the data structure pointed to __________ NULL __________ by *insurance is freed and *insurance is set to NULL. __________ __________ NULL __________ __________ If *insurance is equal to NULL, nothing happens. __________ NULL __________ (Normally **insurance is the same as &(lst_ptr->insurance). ___________ _______ &( ->insurance) ___________ _______ lst_ptr->insurance is used by lst_run to point to the previous _______ ->insurance lst_run _______ answers to the list.) c. Return Value See section Standard Return Values. 16. lst_restoreanswers a. Summary #include "dbpro.h" #include "dbpro.h" - 31 - DialogPro v 2.1 Users Guide Reference Manual int lst_restoreanswers(lst_ptr, insurance) _______ _________ int lst_restoreanswers( , ) _______ _________ lst_rec *lst_ptr; ________ lst_rec * ________ lst_storage **insurance; __________ lst_storage ** __________ b. Description If *insurance is not equal to NULL the state of the lst, lst_ptr, __________ _______ NULL __________ _______ is changed to the answers recorded in the data structure of type lst_storage pointed to by *insurance. The lst_storage data __________ lst_storage lst_storage __________ structure is freed and *insurance is set to NULL. NULL If insurance is equal to NULL, nothing happens. _________ NULL _________ (Normally **insurance is the same as &(lst_ptr->insurance). ___________ _______ &( ->insurance) ___________ _______ lst_ptr->insurance is used by lst_run to point to the previous _______ ->insurance lst_run _______ answers to the list.) c. Return Value See section Standard Return Values. 17. lst_run a. Summary #include "dbpro.h" #include "dbpro.h" int lst_run(lst_ptr, message) _______ _______ int lst_run( , message) _______ _______ list_rec *lst_ptr; ________ list_rec * ________ unsigned int message; ________ unsigned int ________ b. Description The function lst_run executes the messages in the message queue lst_run pointed to by db_queue against the data structure lst_ptr. (It _______ db_queue _______ is very important that a message queue have been initialized via a call to db_switchqueue before calling lst_run.) db switchqueue lst run Before executing the message queue it first places the standard message STORAGE at the tail of the queue and then it places STORAGE message at the head of the queue. All messages are retrieved from the tail of the queue. Each retrieved message is checked first against the global macro list, global macros, and then against the local macro list lst_ptr->macros. If the message is _______ ->macros _______ a macro it is expanded by placing the items pointed to by the macro at the tail of the queue in reverse order. - 32 - DialogPro v 2.1 Users Guide Reference Manual If there are no messages in the message queue lst_run polls the lst_run keyboard and mouse (if one is recognized when wn_init is wn init called.) When activity is noted the keyboard/mouse activity is translated into a message and placed at the tail of the queue. If it is a mouse event the message MOUSE_EVENT is placed at the MOUSE_EVENT tail of the queue. The MOUSE_EVENT message takes the last mouse MOUSE_EVENT event, translates it into a keystroke and places it at the tail of the queue. If the message has a value greater than 256 it is compared against the keystroke-command table, lst_ptr->cmds. If the keystroke is in the table it is interpreted into a standard event. If the message is less than 256 it is interpreted as a standard message. Otherwise it is compared against the the shortcut key of each of the options, starting at the current item + 1 and ending at the current item. The first item whose shortcut key matches the keystroke is selected. If lst_ptr->alpha_confirm is TRUE and lst_ptr->list_type is CHECKLIST then the item is toggles on/off. If lst_ptr->alpha_confirm is TRUE and lst_ptr->list_type is SELECT_ONE then the item is set to TRUE and lst_run exits with a value of CONFIRMED. When one of several exit type messages is received lst_run terminates. The actual message selection/interpretation code explains it a little more succinctly: do { /* get event from queue */ if (!NO_EVENT) event = db_pop(); /* or from keyboard/mouse */ else event = get_lstevent(lst_ptr); } while /* expand macros */ (db_executemacros(event, lst_ptr->macros)); /* if event > 256 see if attached to a standard message */ if (event > 256) { event = lst_opcode(list_ptr, event); ascii = event % 256; } EXECUTE MESSAGE where: message < 256, standard message, - 33 - DialogPro v 2.1 Users Guide Reference Manual message > 256, short cut selection. c. Return Value See section Standard Return Values. 18. lst_select a. Summary #include "dbpro.h" #include "dbpro.h" int lst_select(list_ptr, offset) ____ ___ ______ int lst select ____ ___ ______ list_rec *list_ptr; ____ ___ list rec ____ ___ int offset; ______ int ______ b. Description Dehighlights the currently selected item and highlights the item offset items above (-) or below (+) relative to the current item. ______ Accounts for rollover. Does nothing if offset is equal to 0. ______ c. Return Value See section Standard Return Values. 19. lst_storeanswers a. Summary #include "dbpro.h" #include "dbpro.h" int lst_storeanswers(lst_ptr, insurance) _______ _________ int lst_storeanswers( , ) _______ _________ list_rec *lst_ptr; ________ list_rec * ________ lst_storage **insurance; __________ lst_storage ** __________ b. Description If *insurance is equal to NULL the state of the list, db_ptr, is __________ ______ NULL __________ ______ stored in an interim data structure of type lst_storage and lst_storage *insurance returns the pointer to the data structure. __________ - 34 - DialogPro v 2.1 Users Guide Reference Manual If insurance is not equal to NULL, nothing happens. _________ NULL _________ (Normally **insurance is the same as &(lst_ptr->insurance). ___________ _______ &( ->insurance) ___________ _______ lst_ptr->insurance is used by lst_run to point to the previous _______ ->insurance lst_run _______ answers to the list.) c. Return Value See section Standard Return Values. 20. lst_toggle a. Summary #include "dbpro.h" #include "dbpro.h" int lst_toggle(list_ptr, item) ____ ___ ____ int lst toggle ____ ___ ____ list_rec *list_ptr; ____ ___ list rec ____ ___ int item; ____ int ____ b. Description If lst_ptr->lst_type is equal to CHECKLIST toggles the value of ___ ____ lst type CHECKLIST ___ ____ lst_ptr->selections[item] between TRUE and FALSE and refreshes ___ ____ ____ selections TRUE FALSE ___ ____ ____ the display of item by calling lst_displayitem. lst displayitem If lst_ptr->lst_type is equal to SELECT_ONE all other items in ___ ____ lst type SELECT ONE ___ ____ the list are set to FALSE, lst_ptr->selections[item] is set to ___ ____ ____ FALSE selections ___ ____ ____ TRUE, and the entire list is refreshed. TRUE The value of lst_ptr->available[item] must be TRUE. ___ ____ ____ available TRUE ___ ____ ____ c. Return Value FALSE If lst_ptr->available[item] is FALSE the function ___ ____ ____ FALSE available FALSE ___ ____ ____ terminates early and returns FALSE. FALSE TRUE function executed properly. TRUE - 35 - DialogPro v 2.1 Users Guide Reference Manual C. Standard Return Values ABORTED User exited by abort CONFIRMED User exited by confirm ASCENDED User exited by ascending DESCENDED User exited by descending MOUSED User exited by clicking the mouse outside of the image of the window associated with the dialog box. MENUED User exited by confirming a pull down menu OK No errors detected INVALID_QUESTION_TYPE Dialog box's question list has a question of a type not defined in dbpro.h BAD_PARAMS Coordinates or variables were outside of a specified range NULL_POINTER Passed a NULL pointer OUT_OF_MEMORY Function could not allocate enough memory to create required data structures - 36 - DialogPro v 2.1 Users Guide Reference Manual D. Data structures 1. button char question_type must be set to BUTTON. ________ ____ char BUTTON ________ ____ unsigned char tile_handle The question is displayed in this ____ ______ unsigned char ____ ______ tile. tile_handle must be a valid ____ ______ tile handle. int (*whenon) ______ int ______ (dialog_box *) dialog box int (*whenoff) _______ int _______ (dialog_box *) dialog box int (*action)(dialog_box *) Pointers to edit checking ______ int dialog box ______ routines. db_run executes each db run routine under these conditions. On selecting the question whenon is ______ executed. On selecting a question other than the current question or on exiting db_run whenoff is _______ db run _______ executed. On pressing the button action is executed. whenoff ______ must return TRUE or the attempt to TRUE navigate to another question will fail. If any routine is set to NULL it is not executed. db_run NULL always passes the current dialog box pointer to each edit checking function. char *statement A string representing the statement _________ char _________ to appear inside the button. int statementx, statementy Upper left coordinate of the __________ __________ int __________ __________ button. int key Identical to keybind (below), but ___ int ___ the button also becomes the selected question. char *boxchars Box drawing characters to be used ________ char ________ in drawing the button border. Use NULL to indicate no borders. See NULL vs_box in The WindowPro reference vs box manual for further explanation. char shading Shading style to be used when _______ char _______ drawing the box surrounding the button. See vs_box in The vs box WindowPro reference manual for further explanation. - 37 - DialogPro v 2.1 Users Guide Reference Manual int cmdkey On pressing a button this value is ______ int ______ placed at the tail of the message queue. int keybind This value binds the keyboard code, _______ int _______ keybind, to the button. Generating _______ this keyboard code will 1-flash the button, 2-place cmdkey at the tail ______ of the message queue, and 3-execute action. Note that the selected ______ question is not effected. char continuous If TRUE, holding the mouse cursor __________ char TRUE __________ on the button repeatedly places PRESS_BUTTON at the tail of the PRESS BUTTON message queue. If FALSE only a FALSE mouse release will place a single PRESS_BUTTON at the tail of the PRESS BUTTON message queue. int exitval If cmdkey results in exiting _______ ______ int _______ ______ db_run. db_run will exit with the db run db run value exitval. _______ 2. db_colors db_colors represents the attributes to be used when updating a dialog box. Typically you would set up one db_colors structure for use with all dialog boxes to establish a personality for your system. You may also want to have various color schemes for different types of dialog boxes. unsigned char title_bg, __________ unsigned char __________ title_fg The background and foreground color ______________________________ to use when updating a title. unsigned char question_bg, ____________ unsigned char ____________ question_fg The background and foreground color ______________________________ to use when updating the statement portions of questions. unsigned char response_bg, _____________ unsigned char _____________ response_fg The background and foreground color ______________________________ to use when updating an unselected, available response. unsigned char un_bg, un_fg The background and foreground color ________________ unsigned char ________________ to use when updating an unselected, unavailable response. - 38 - DialogPro v 2.1 Users Guide Reference Manual unsigned char sun_bg, sun_fg The background and foreground color ______________ unsigned char ______________ to use when updating a selected, unavailable response. unsigned char select_bg, ____________ unsigned char ____________ select_fg The background and foreground color ______________________________ to use when updating a selected, available response. unsigned char key_bg, key_fg The background and foreground color ________________ unsigned char ________________ to use when updating a statement or list element. Each character preceded by a ~ in a statement or list element is output in this color. If there are no ~s in the string the first character is output with this color. Used to indicate the shortcut keys for a question. unsigned char edit_bg, __________ unsigned char __________ edit_fg The background and foreground color _______ to use when using the line editor in a free_form or reducer. 3. db_delimiters db_delimiters represents the characters to be placed around the response portion of questions within a dialog box. Typically you would set up one db_delimiters structure for use with all dialog boxes to establish a personality for your system. You may also want to have various delimiter schemes for different types of dialog boxes. unsigned char *ff_boxchars The characters to place around the ___________ unsigned char ___________ response portion of a free_form free_form question. These character arrays are defined the same as the window border character arrays. Note that any NULL characters are simply not NULL output. This means that you do not have to triple space questions as you would by putting a complete box around each, but could just define delimiters on either side (as in DBPRO 1.1) or even none at all. unsigned char *mc_boxchars Same as ff_boxchars, but for ___________ ___________ unsigned char ___________ ___________ multi_choice questions. - 39 - DialogPro v 2.1 Users Guide Reference Manual unsigned char *r_boxchars Same as ff_boxchars, but for __________ ___________ unsigned char __________ ___________ reducer questions. char *check_on, *check_off The characters to be placed to the ________ _________ char ________ _________ left of a checkbox statement indicating that the item is checked or not checked, e.g. [ ] or [X]. char *radio_on, *radio_off Same as check_on, check_off but for ________ _________ char ________ _________ radio buttons. 4. dialog_box dialog_box is the basic data type used by almost all of the high ______ ___ level functions. The dialog box data structure consists of the following members. int handle Every dialog box must be related to ______ int ______ an existing window. If handle is ______ not a valid window handle a window handle is created using the window information at the end of this structure. (*post_size)(void *) after db_run processes any sizing ____ ____ void db run ____ ____ messages it executes post_size ____ ____ passing db_ptr as argument. int (*post_move)(void *) after db_run processes any moving ____ ____ int void db run ____ ____ messages it executes post_move ____ ____ passing db_ptr as argument. char move_ok db_run will not process any moving ____ __ char db run ____ __ messages if move_ok is FALSE. ____ __ FALSE ____ __ char size_ok db_run will not process any sizing ____ __ char db run ____ __ messages if size_ok is FALSE. ____ __ FALSE ____ __ void **questions pointer to an array representing _________ the list of questions which comprise the dialog box. The last item in the array must be a NULL pointer. char *available pointer to an array corresponding _________ char _________ to the above array, where a value of FALSE indicates that the response to the corresponding question cannot be modified. - 40 - DialogPro v 2.1 Users Guide Reference Manual char id_select The currently selected question as __ ______ char __ ______ an offset in the question array (questions, above.) _________ int *cmds An array of extended keyboard codes ____ int ____ corresponding to the standard messages, where standard message 1 (PRESS_BUTTON) corresponds to keyboard code in position 0, message 2 (CONFIRM) corresponds to the keyboard code in position 1, etc. This array is used to interpret keyboard codes into messages. cmds is generally set to ____ the supplied default keyboard commands default_db_cmds. default_db_cmds char bg_operation If FALSE, when db_run is executed __ _________ char FALSE db run __ _________ the dialog box window is brought to the top of the stack via a call to wn_openw. If FALSE and the window wn openw FALSE is on the screen it remains in its position in the stack. If FALSE FALSE and the window is not on the screen it is displayed via a call to wn_openw. In a desktop type wn_openw application the desktop itself can be setup as a type of dialog box (a row of pull down menus along the top, with perhaps some buttons representing disk drives, etc.) In this case we would not want the dialog box brought to the top of the stack since it would obscure all of the windows on the screen. This type of dialog box would generally set bg_operation to TRUE. __ _________ TRUE __ _________ storage *insurance A pointer to a data structure _________ storage _________ representing the previous answers to the dialog box questions. Always set this to NULL. NULL int **macros A list of macros associated with ______ int ______ this dialog box. This array must be NULL terminated. Each NULL individual macro must be constructed in this manner: [message to replace, number of replacement messages, nth replacement message,...., first replacement message] - 41 - DialogPro v 2.1 Users Guide Reference Manual Note that the first item represents the message to be replaced, the second item represents the number of replacement items, and the succeeding items represent the messages to replace it with (note that these are in reverse order. db_colors *colors Determines what attributes to use ______ db_colors ______ when displaying a dialog box. db_delimiters *delimiters Determines what delimiters to place __________ db_delimiters __________ around various question types. if handle (above) is not a valid window handle we use this info ______ to create a window .... unsigned virtual_rows number of row & columns in the ____________ unsigned ____________ unsigned virtual_columns virtual screen. _______________ unsigned _______________ unsigned physical_x location of the upper left hand __________ unsigned __________ unsigned physical_y corner of the dialog box window. __________ unsigned __________ unsigned virtual_x, virtual_y upper left coordinate of the ____________________ unsigned ____________________ dialog box's virtual screen which maps to the upper left hand corner of the lists frame. unsigned port_rows number of rows & columns within the _________ unsigned _________ unsigned port_columns dialog box's frame ____________ unsigned ____________ unsigned shading style of shading to use for the _______ unsigned _______ dialog box's frame. See The WindowPro manual for further explanation. char *name1, *name2 a string to place in the top & _____ _____ char _____ _____ bottom part or the dialog box's frame. unsigned char *boxchars The characters to use when creating ________ unsigned char ________ the dialog box's frame. See The WindowPro manual for further explanation unsigned char scroll_bars The scroll bar style to use when ___________ unsigned char ___________ creating the dialog box's frame. See The WindowPro manual for further explanation. - 42 - DialogPro v 2.1 Users Guide Reference Manual 5. free_form char question_type must be set to FREE_FORM ________ ____ char FREE FORM ________ ____ unsigned char tile_handle The question is displayed in this ____ ______ unsigned char ____ ______ tile. tile_handle must be a valid ____ ______ tile handle. int (*whenon) ______ int ______ (dialog_box *) dialog box int (*whenoff) _______ int _______ (dialog_box *) dialog box int (*action)(dialog_box *) Pointers to edit checking ______ int dialog box ______ routines. db_run executes each db run routine under these conditions. On selecting the question whenon is ______ executed. On selecting a question other than the current question or on exiting db_run whenoff is _______ db run _______ executed. On exiting the line editor action is executed. action ______ ______ must return TRUE or you will not be TRUE able to exit the line editor. whenoff must return TRUE or the _______ TRUE _______ attempt to navigate to another question will fail. If any routine is set to NULL it is not executed. NULL db_run always passes the current dialog box pointer to each edit checking function. char *statement A string representing the statement _________ char _________ portion of the question. int statementx, statementy The left coordinate of the __________ __________ int __________ __________ statement. int key Shortcut key. ___ int ___ char *response The current response to the ________ char ________ question. This must be a dynamically allocated string. On confirming a new response this response will be freed. char *default_response If response is NULL when the line editor is invoked, or the response is displayed, response will be set equal to a dynamically allocated copy of this string. int responsex, responsey The coordinate where the response _________ _________ int _________ _________ will be displayed. - 43 - DialogPro v 2.1 Users Guide Reference Manual int responselen The maximum displayed length of the ___________ int ___________ response. The actual length of the response can be up to 1000 characters. char *storage The previous response to the _______ char _______ question. Should always be set to NULL. NULL char **target The char * pointer pointed to by ______ char ______ target is updated with the value of ______ response on exiting the db_run. ________ db run ________ int cursor_position The position of the cursor on ______ ________ int ______ ________ confirming the current response to the question. int **macros See dialog_box for further ______ int dialog box ______ explanation. char refresh If TRUE the statement and question _______ char _______ delimiters are output. Set this to true on initialization. Each time the statement and delimiters are displayed this value is reset to FALSE. 6. list unsigned char tile_handle The question is displayed in this ____ ______ unsigned char ____ ______ tile. tile_handle must be a valid ____ ______ tile handle. int (*whenon) ______ int ______ (dialog_box *) dialog box int (*whenoff) _______ int _______ (dialog_box *) dialog box int (*action)(dialog_box *) Pointers to edit checking ______ int dialog box ______ routines. db_run executes each db run routine under these conditions. On selecting the question whenon is ______ executed. On selecting a question other than the current question or on exiting db_run whenoff is _______ db run _______ executed. On exiting the list action is executed. Until action ______ ______ returns TRUE the user will be TRUE unable to exit the list. whenoff _______ must return TRUE or the attempt to TRUE navigate to another question will fail. If any routine is set to NULL it is not executed. db_run NULL - 44 - DialogPro v 2.1 Users Guide Reference Manual always passes the current dialog box pointer to each edit checking function. char *statement A string representing the statement _________ char _________ portion of the question. int statementx, statementy The left coordinate of the __________ __________ int __________ __________ statement. int key Shortcut key. ___ int ___ unsigned int handle A window handle. The window should ______ unsigned int ______ have the number of rows and columns and appropriate border type and style as desired for the scrolling list box. If this is not a valid window handle. The window will be created using the window parameters below. if handle (above) is not a valid window handle we use this info ______ to create a window .... unsigned virtual_rows number of row & columns in the ____________ unsigned ____________ unsigned virtual_columns virtual screen. _______________ unsigned _______________ unsigned physical_x location of the upper left hand __________ unsigned __________ unsigned physical_y corner of the list within the __________ unsigned __________ dialog box window. unsigned virtual_x upper left coordinate of the list's _________ unsigned _________ unsigned virtual_y virtual screen which maps to the _________ unsigned _________ upper left hand corner of the lists frame. unsigned port_rows number of rows & columns within the _________ unsigned _________ unsigned port_columns list's frame ____________ unsigned ____________ unsigned shading style of shading to use for the _______ unsigned _______ list's frame. See The WindowPro manual for further explanation. char *name1, *name2 a string to place in the top & _____ _____ char _____ _____ bottom part or the list's frame. unsigned char *boxchars The characters to use when creating ________ unsigned char ________ the list's frame. See The WindowPro manual for further explanation - 45 - DialogPro v 2.1 Users Guide Reference Manual unsigned char scroll_bars The scroll bar style to use when ___________ unsigned char ___________ creating the list's frame. See The WindowPro manual for further explanation. Note : If handle is a valid window handle than you do not need to ______ set the above structure members to meaningful values. char list_type Set this to SELECT_ONE for a radio ____ ____ char SELECT ONE ____ ____ buttons style list. Set this to CHECKLIST to toggle more than one CHECKLIST item on and off. char **options An array of strings representing _______ char _______ the items in the list. int offset An offset into the above array ______ int ______ representing the currently selected item. char *selections An array of chars corresponding the __________ char __________ above array. If selections[0] is __________ TRUE indicates that the first item TRUE in the list is toggle on, If selections[1] is TRUE indicates __________ TRUE __________ that the second item in the list is toggled on. selections[2] == 2 _____________ indicates that the third item represents a title within the list. char *available pointer to an array corresponding _________ char _________ to the above array, where a value of FALSE indicates that the state FALSE of the corresponding item cannot be modified. char *on, *off Strings which represent the on/off __ ___ char __ ___ states of each item in the list, e.g. "ON" and "OFF", or "XX" and "--", etc. list_rec *list_ptr Used internally. Set this to NULL. ____ ___ list rec NULL ____ ___ char **target A pointer to an array of chars. On ______ char ______ exiting db_run *target is set equal ______ db run ______ to selections. __________ int **macros See explanation at dialog_box. ______ int dialog box ______ - 46 - DialogPro v 2.1 Users Guide Reference Manual 7. list_rec list_rec is the basic data type used by almost all of the high ________ level list-oriented functions. The list_rec data structure ________ consists of the following members. int handle Every list must be related to an ______ int ______ existing window. handle must be a ______ valid window handle. int tile_handle Every list must be related to an ___________ int ___________ existing tile. tile_handle must be ___________ a valid tile handle. char list_type Set to CHECKLIST to allow more than _________________________ char CHECKLIST _________________________ one item to be toggled on/off. Set to SELECT_ONE so that as one item SELECT ONE is toggled on all other items are toggled off. char move_ok lst_run will not process any moving ____ __ char lst run ____ __ messages if move_ok is FALSE. ____ __ FALSE ____ __ char size_ok lst_run will not process any sizing ____ __ char lst run ____ __ messages if size_ok is FALSE. ____ __ FALSE ____ __ char auto_vert If TRUE, on calling lst_run the ____ ____ char TRUE lst run ____ ____ window is automatically resized so that it has the same number of rows as there are items in the list. char auto_horiz If TRUE, on calling lst_run the ____ _____ char TRUE lst run ____ _____ window is automatically resized so that it is as wide as the widest option. char alpha_confirm If TRUE, list_type is SELECT_ONE, _____ _______ ____ ____ char TRUE SELECT ONE _____ _______ ____ ____ and executing lst_run, pressing lst run any alpha selects the next item bound to the key, toggles it on, and exits lst_run with a value of lst run CONFIRMED. CONFIRMED If TRUE, list_type is CHECKLIST, TRUE CHECKLIST and executing lst_run, pressing any lst run alpha key selects the next item in the list bound to that key and toggles the item on. int *cmds An array of extended keyboard codes ____ int ____ corresponding to the standard messages, where standard message 1 (PRESS_BUTTON) corresponds to keyboard code in position 0, - 47 - DialogPro v 2.1 Users Guide Reference Manual message 2 (CONFIRM) corresponds to the keyboard code in position 1, etc. This array is used to interpret keyboard codes into messages. cmds is generally set to ____ the default keyboard commands default_db_cmds. default_db_cmds char bg_operation If FALSE, when db_run is executed __ _________ char FALSE db run __ _________ the dialog box window is brought to the top of the stack via a call to wn_openw. If FALSE and the window wn openw FALSE is on the screen it remains in its position in the stack. If FALSE FALSE and the window is not on the screen it is displayed via a call to wn_openw. In a desktop type application the desktop itself can be setup as a type of dialog box (a row of pull down menus along the top, with perhaps some buttons representing disk drives, etc.) In this case we would not want the dialog box brought to the top of the stack since it would obscure all of the windows on the screen. This type of dialog box would generally set bg_operation to TRUE. __ _________ TRUE __ _________ lst_storage *insurance A pointer to a data structure _________ lst_storage _________ representing the previous answers to the list. Always set this to NULL. NULL int **macros A list of macros associated with ______ int ______ this dialog box. The list must be NULL terminated (i.e. the last item NULL in the array must be NULL.) Each NULL individual macro must be constructed in this manner: [message to replace, nth message,...., first message, NULL] NULL Note that the first item represents the message to be replaced, the succeeding items represent the messages to replace it with (note that these are in reverse order,) and the last item must be a NULL. NULL - 48 - DialogPro v 2.1 Users Guide Reference Manual char *on, *off Strings which represent the on/off __ ___ char __ ___ states of each item in the list, e.g. "ON" and "OFF", or "XX" and "--", etc. char **options An array of strings representing _______ char _______ the items in the list. The last element in the array must be NULL. NULL char *selections An array of chars corresponding the __________ char __________ above array. If selections[0] is __________ TRUE indicates that the first item TRUE in the list is toggle on, If selections[1] is TRUE indicates __________ TRUE __________ that the second item in the list is toggled on, etc. char *available pointer to an array corresponding _________ char _________ to the above array, where a value of FALSE indicates that the state FALSE of the corresponding item cannot be modified. unsigned *keybind An array of ints corresponding to _______ unsigned _______ the above array where each element in the array represents an extended keyboard code or an ascii code. These values bind the options to keystrokes (see alpha_confirm, _____ _______ above, for further explanation.) If an ascii code is used selection in case insensitive. If an extended keyboard code is used it must match exactly. int selected An offset into the above array ________ int ________ representing the item in the list which is currently selected. int These values are used internally int and should not be modified. You may however read these variables although they are not always guaranteed to be up to date. optlen, The length of the longest option in ______ the list. taglen, The length of the longest on/off ______ indicator. numopts The number of items in the list. _______ - 49 - DialogPro v 2.1 Users Guide Reference Manual db_colors *colors A pointer to a color scheme ______ db_colors ______ structure. Determines which attributes to use when displaying different parts of the list. unsigned maxcols determines the number of columns in _______ unsigned _______ the list. If this number is larger than the number of items in the list, creates a vertical list, like a lotus menu. unsigned If handle (above) is not a valid ______ unsigned ______ window handle these items are used to create a window for the list. physical_x, physical_y ___________________________ virtual_x, virtual_y, __________________________ virtual_rows, __________________ virtual_columns ____________________ port_rows, port_columns ____________________________ shading ____________ char *name1, *name2 _____ _____ char _____ _____ char unsigned *boxchars; ________ char unsigned ________ 8. multi_choice char question_type must be set to MULTI_CHOICE. ________ ____ char MULTI CHOICE ________ ____ unsigned char tile_handle The question is displayed in this ____ ______ unsigned char ____ ______ tile. tile_handle must be a valid ____ ______ tile handle. int (*whenon) int (dialog_box *) dialog box int (*whenoff) int (dialog_box *) dialog box int (*action)(dialog_box *) Pointers to edit checking ______ int dialog box ______ routines. db_run executes each db run routine under these conditions. On selecting the question whenon is executed. On selecting a question other than the current question or on exiting the db_run whenoff is _______ db run _______ executed. On confirming the response to the current question action is executed. ______ whenoff must return TRUE or the TRUE attempt to navigate to another question will fail. If any routine is set to NULL it is not executed. NULL - 50 - DialogPro v 2.1 Users Guide Reference Manual db_run always passes the current dialog box pointer to each edit checking function. char *statement A string representing the statement _________ char _________ portion of the question. int statementx, statementy Displays the statement portion of __________ __________ int __________ __________ the question at these coordinates. char *response_mask If not set to NULL, db_run ________ ____ char NULL db run ________ ____ suppresses the display of statement and puts this string in place of the response. Makes multiple choice question behave like a pull down menu. char **response_list An array of strings representing ________ ____ char ________ ____ the available choices in the multiple choice question. The last element in the array must be set to NULL. NULL char *available An array of chars corresponding to _________ char _________ the above array. If available[0] is _________ FALSE the first item cannot be FALSE chosen as the response, If available[1] is TRUE the second _________ TRUE _________ item in response_list can be chosen ________ ____ as the response. A 2 indicates that the list element is a title. int response_offset The current response to the ________ ______ int ________ ______ question as an offset into response_list. ________ ____ int responsex, responsey The coordinates where the response _________ _________ int _________ _________ portion of the question is displayed. int responselen The displayed length of the ___________ int ___________ response. The actual response can be longer. int key The extended keyboard code for the ___ int ___ shortcut key (when executing db_run, if the user presses the db run shortcut key he navigates directly to associated question.) unsigned int aux_handle A window handle. Required for the ___ ______ unsigned int ___ ______ pull down list. Note if this is not a valid window handle it will be automatically created. - 51 - DialogPro v 2.1 Users Guide Reference Manual unsigned char aux_tile A valid tile handle. Required for ___ ____ unsigned char ___ ____ the pull down list. if aux_handle (above) is not a valid window handle this info to __________ create a window ... unsigned char *boxchars ________ unsigned char ________ char *major_head, *minor_head __________ __________ char __________ __________ char shading _______ char _______ list_rec *list_ptr Used internally. Set this to NULL. ____ ___ list rec NULL ____ ___ int *target A pointer to an int to set equal to ______ int ______ response_offset on exiting db_run. _______________ db run _______________ int **macros See dialog_box for an explanation. ______ int dialog box ______ char refresh When this value is true and the _______ char _______ question is displayed the statement and delimiters are output to the dialog box's virtual screen. Otherwise, just the response is sent. Typically you initialize this to TRUE. Every time the TRUE question is displayed this is reset to FALSE. FALSE unsigned maxcols Indicates how many columns to use _______ unsigned _______ when displaying the pull down list. 9. rcbutton This structure is used to represent either a radio button or a check box. char question_type must be set to RCBUTTON. ________ ____ char RCBUTTON ________ ____ unsigned char tile_handle The question is displayed in this ____ ______ unsigned char ____ ______ tile. tile_handle must be a valid ____ ______ tile handle. int (*whenon) ______ int ______ (dialog_box *) dialog box int (*whenoff) _______ int _______ (dialog_box *) dialog box int (*action)(dialog_box *) Pointers to edit checking ______ int dialog box ______ routines. db_run executes each db run routine under these conditions. On selecting the question whenon is ______ executed. On selecting a question other than the current question or - 52 - DialogPro v 2.1 Users Guide Reference Manual on exiting db_run whenoff is _______ db run _______ executed. On pressing the rcbutton action is executed. ______ whenoff must return TRUE or the TRUE attempt to navigate to another question will fail. If any routine is set to NULL it is not executed. NULL db_run always passes the current dialog box pointer to each edit checking function. char *statement A string representing the statement _________ char _________ to appear to the right of the rcbutton's checkoff area. int statementx, statementy left coordinate of the rcbutton. __________ __________ int __________ __________ int key Shortcut key. ___ int ___ unsigned char btype Set to CHECK if a checkbox, or _____ unsigned char _____ RADIO(N) where N is a number between 0 and 254. Only one rcbutton in the radio group number N can be "on" at any moment. char checked Set to TRUE if the rcbutton is _________________________ char _________________________ checked. char *target The variable pointed to by target ________________________ ______ char ________________________ ______ will be updated with the value of checked on exiting the dialog box. _______ 10. reducer char question_type must be set to REDUCER. ________ ____ char REDUCER ________ ____ unsigned char tile_handle The question is displayed in this ____ ______ unsigned char ____ ______ tile. tile_handle must be a valid ____ ______ tile handle. int (*whenon) int (dialog_box *) dialog box int (*whenoff) int (dialog_box *) dialog box int (*action)(dialog_box *) Pointers to edit checking ______ int dialog box ______ routines. db_run executes each db run routine under these conditions. On selecting the question whenon is executed. On selecting a question other than the current question or on exiting the db_run whenoff is _______ db run _______ executed. On confirming the response to the current - 53 - DialogPro v 2.1 Users Guide Reference Manual question action is executed. ______ whenoff must return TRUE or the TRUE attempt to navigate to another question will fail. If any routine is set to NULL it is not executed. NULL db_run always passes the current dialog box pointer to each edit checking function. char *statement A string representing the statement _________ char _________ portion of the question. int statementx, statementy Displays the statement portion of __________ __________ int __________ __________ the question at these coordinates. char **response_list An array of strings representing ________ ____ char ________ ____ the available choices in the multiple choice question. The last element in the array must be set to NULL. NULL char *available An array of chars corresponding to _________ char _________ the above array. If available[0] is _________ FALSE the first item cannot be FALSE chosen as the response, If available[1] is TRUE the second _________ TRUE _________ item in response_list can be chosen ________ ____ as the response, etc. char *response The current response to the _________ char _________ question. Must be a dynamically allocated string as when a new response is confirmed the previous response is freed. int responsex, responsey The coordinates where the response _________ _________ int _________ _________ portion of the question is displayed. int responselen The displayed length of the ___________ int ___________ response. The actual response can be longer. int key The extended keyboard code for the ___ int ___ shortcut key (when executing db_run, if the user presses the db run shortcut key he navigates directly to associated question.) int cursor_position The position of the cursor when the ______ ________ int ______ ________ current response was confirmed. - 54 - DialogPro v 2.1 Users Guide Reference Manual char **target A pointer to a variable to set _______ char _______ equal to response on exiting ________ db_run. db run int **list_macros Macros used while in the pull down ___________ int ___________ list portion of a reducer question. See dialog_box for an dialog box explanation. int **edlin_macros Macros used while in the lide ____________ int ____________ editor portion of a reducer question. See dialog_box for an dialog box explanation. unsigned int aux_handle A window handle. Required for the ___ ______ unsigned int ___ ______ pull down list. Note if this is not a valid window handle it will be automatically created. unsigned char aux_tile A valid tile handle. Required for ___ ____ unsigned char ___ ____ the pull down list. if aux_handle (above) is not a valid window handle this info to __________ create a window ... unsigned char *boxchars ________ unsigned char ________ char *major_head, *minor_head __________ __________ char __________ __________ char shading _______ char _______ list_rec *list_ptr Used internally. Set this to NULL. ____ ___ list rec NULL ____ ___ char refresh When this value is true and the _______ char _______ question is displayed the statement and delimiters are output to the dialog box's virtual screen. Otherwise, just the response is sent. Typically you initialize this to TRUE. Every time the TRUE question is displayed this is reset to FALSE. FALSE unsigned maxcols Indicates how many columns to use _______ unsigned _______ when displaying the pull down list. 11. scroll_txt This data structure is used to define the scrolling text type questions. This question type is different from the other question types because you must supply the address to the 'controlling' function. Two sample controlling functions are provided. - 55 - DialogPro v 2.1 Users Guide Reference Manual char question_type Must be set to SCROLL_TXT. _____________ char SCROLL_TXT _____________ unsigned char tile_handle The question is displayed in this ____ ______ unsigned char ____ ______ tile. tile_handle must be a valid ____ ______ tile handle. int (*whenon) int (dialog_box *) dialog box int (*whenoff) int (dialog_box *) dialog box int (*action)(dialog_box *) Pointers to edit checking ______ int dialog box ______ routines. db_run executes each db run routine under these conditions. On selecting the question whenon is executed. On selecting a question other than the current question or on exiting the db_run whenoff is _______ db run _______ executed. On confirming the response to the current question action is executed. ______ whenoff must return TRUE or the TRUE attempt to navigate to another question will fail. If any routine is set to NULL it is not executed. NULL db_run always passes the current dialog box pointer to each edit checking function. int (far *control) _______ int far _______ (dialog_box *, int) On executing the question control dialog_box int is passed to this routine. In the event of a MOUSE_EVENT occuring MOUSE_EVENT within the question's region the second parameter will be set to MOUSE_EVENT. Otherwise the MOUSE_EVENT parameter will be 0. void *misc_ptr Because the use of SCROLL_TXT is ________ void SCROLL_TXT ________ open-ended it may be necessary to associate additional data with the question. You can point to a structure containing this additional data using this pointer. int boxx, boxy The upper left corner of the ____ ____ int ____ ____ question will begin at this coordinate within the dialog box window. unsigned int aux_handle The question requires a window for __________ unsigned int __________ some interim processing. Create a window and assign the handle to - 56 - DialogPro v 2.1 Users Guide Reference Manual this data structure member. The question region will be same size as this window. int **macros See dialog_box for further ______ int dialog box ______ explanation. 12. title Use this to display titles in dialog boxes. char question_type Must be set to TITLE. _________________________ char TITLE _________________________ unsigned char tile_handle Indicates which tile to display the ________________ unsigned char ________________ title in. char *statement Indicates the title string. _________ char _________ int statementx, statementy Where to locate the title. __________________________ int __________________________ char center_justify If TRUE ignores statementx and _________________________ __________ char TRUE _________________________ __________ center justifies the title within the virtual screen. - 57 - DialogPro v 2.1 Users Guide Reference Manual E. Global variables 1. db_head, db_tail, db_queue int *db_queue An array of ints representing the __ _____ int __ _____ circular message queue unsigned char *db_head A pointer to a char containing the __ ____ unsigned char __ ____ offset into db_queue where the last __ _____ message in the queue is located. unsigned char *db_tail A pointer to a char containing the __ ____ unsigned char __ ____ offset into db_queue where the next __ _____ message to be used is located. 2. default_db_cmds A default keyboard-command table. 3. idle void (* idle)(void *) ____ void void ____ the idle function is repeatedly called in the keyboard/mouse polling loop. The function pointed to by idle is passed a ____ pointer to the active dialog_box or list_rec on each call. Use dialog_box list_rec this to place time limits on a response, update a time and date field, or do other real time updating. Note that the timing of the polling loop can vary based on whether keyboard typematic is active, the mouse buttons are up or down, or whether or not a mouse is installed. 4. monitor_switch, _fg, _bg, _speed, _wdw, _tile These values determine how the debug monitor operates. The debug monitor will display the queue events in a window. You can watch these queue events to determine if a dialog box is behaving properly. extern unsigned int extern unsigned int monitor_wdw The handle of the window where the ___________ debug info will be displayed. The extern unsigned char extern unsigned char monitor_tile The tile handle where the debug ______________ info will be displayed. This tile's virtual screen needs to be about 70 characters wide. extern int monitor_speed 0 = no delay, > 0 = more delay, -1 _____________ extern int _____________ = step through by keystroke. - 58 - DialogPro v 2.1 Users Guide Reference Manual extern int monitor_switch 0 if monitor is OFF, 1 if it is ON. ______________ extern int ______________ extern unsigned char extern unsigned char monitor_fg, monitor_bg The background and foreground color __________ __________ that the monitor info will display in. 5. mouse_sensitivity The timeout value to be used when calling kb_mouseclicks. 15 kb mouseclicks seems to work just about right. But you may want to fine tune it for other systems or give the user access to this value--like the MAC or Microsoft Windows. - 59 - DialogPro v 2.1 Users Guide Reference Manual F. Messages 1. Dialog Box Each message is translated as follows at the dialog box level by _______________________ db_run (several of the messages transfer porcessing to question level--to see how messages are interpreted at the question level review the following section): DO_NOTHING Does nothing. DO_NOTHING PRESS_BUTTON If the current question (indicated by PRESS_BUTTON db_ptr->id_select) is a button the value ______ ->id_select ______ BUTTONQUEST(db_ptr->id_select)->cmd_key is ______ BUTTONQUEST( ->id_select)->cmd_key ______ placed at the tail of the queue and the global variable button_press is set to BUTTONQUEST(db_ptr->id_select)->exitval. ______ BUTTONQUEST( ->id_select)->exitval ______ If the current question is a multiple choice question the current response + 1 (with wrap around from the last response to the first) becomes the new response. On the other questions, nothing happens. CONFIRM If the current question is a multiple choice CONFIRM and CURRMC->response__mask does not equal CURRMC->response__mask NULL the message DESCEND is placed at the NULL DESCEND tail of the queue. Otherwise, if at the dialog box level, it executes db_freestorage. Exits db_run with db_freestorage db_run the value CONFIRMED and places CONFIRM at the CONFIRMED CONFIRM tail of the queue if button_press is equal to button_press 0, otherwise it exits with the value of button_press. button_press ABORT Executes db_restoreanswers and exits db_run. ABORT db_restoreanswers db_run Exits with the value ABORTED and places ABORT ABORTED ABORT at the tail of the queue if button_press is button_press equal to 0, otherwise it exits with the value button_press. button_press UP, DOWN, LEFT, RIGHT, HOME, END, BIG_RIGHT, BIG_LEFT, BACKSPACE UP, DOWN, LEFT, RIGHT, HOME, END, BIG_RIGHT, BIG_LEFT, BACKSPACE Passes the event onto the current question by putting the respective event at the tail of the queue and then placing a DESCEND at the tail of the queue. In the case of a BUTTON the event is ignored. In the case of radio button selects the next or previous radio button in the radio button group. - 60 - DialogPro v 2.1 Users Guide Reference Manual BIG_UP Does nothing. BIG_UP BIG_DOWN " BIG_DOWN BIG_HOME Selects the first question in the dialog box. BIG_HOME BIG_END Selects the last question in the dialog box. BIG_END ASCEND Executes db_freestorage. Exits db_run with ASCEND db_freestorage db_run the value ASCENDED if button_press is equal ASCENDED button_press to 0, otherwise it exits with the value of button_press. button_press DESCEND If the current question is a multiple choice, DESCEND "pulls down" the list of selection in a vertical list, with the current response highlighted. If the current question is a free form or reducer, enters the line editor. If the current question is a list, the cursor moves inside of the scrolling list and the item which was highlighted when the user last executed the list is highlighted. If the current question is a button, does nothing. EXPAND If the current question is a multiple choice EXPAND question it "pulls down" the available responses to the question in a vertical list. If the current question is a reducer is "pulls down" ALL of the available responses to the question in a vertical list. DELETE does nothing. DELETE MOUSE_CONFIRM Executes db_freestorage. Exits db_run with MOUSE_CONFIRM db_freestorage db_run the value MOUSED and places MOUSE_EVENT at MOUSED MOUSE_EVENT the tail of the queue. MOUSE_EVENT Interprets the last mouse event (prev_x, MOUSE_EVENT prev_x prev_y, and prev_click) into keystroke. The prev_y prev_click keystroke is then placed at the tail of the queue. MOUSE_DESCEND If the current question is a reducer or a MOUSE_DESCEND multiple choice question db_run calls the db_run line editor and places the cursor at the location clicked on in the text. - 61 - DialogPro v 2.1 Users Guide Reference Manual If the current question is a list, MOUSE_EVENT is placed at the tail of the MOUSE_EVENT queue and the list is executed. STORE Executes db_storeanswers. STORE db_storeanswers. RESTORE Executes db_restoreanswers. RESTORE db_restoreanswers FREE_STORAGE Executes db_freestorage. FREE_STORAGE db_freestorage POSITION Selects the question based on the value of POSITION the next integer in the event queue. POSITION_TOGGLE Does nothing. POSITION_TOGGLE POSITION_CONFIRM Does nothing. POSITION_CONFIRM EXECUTE Executes a function by generating a function EXECUTE pointer based on the next two instructions in the event queue. The function is passed db_ptr as a parameter. The function is db_ptr continually execute until it returns an integer value of TRUE. TRUE alphanumeric If on a free_form or reducer, erases the current response, makes the character pressed the first character in the new response and enters the line editor. If on a multiple choice, selects the next item beginning with that character. NEXT, PREVIOUS Selects the next/previous question. NEXT PREVIOUS If db_ptr->size_ok is TRUE then: ______ ->size_ok ______ SIZE_LT Pulls right border of window (db_ptr->handle) ______ SIZE_LT ->handle ______ in one character. SIZE_RT Pulls right border of window (db_ptr->handle) ______ SIZE_RT ->handle ______ out one character. SIZE_UP Pulls bottom border of tile (db_ptr->handle, ______ SIZE_UP ->handle ______ QUESTION->tile_handle) up one character. QUESTION->tile_handle SIZE_DN Pulls bottom border of tile down one SIZE_DN character. BIG_SIZE_LT Same as above but by 8 characters. BIG_SIZE_LT BIG_SIZE_RT " BIG_SIZE_RT BIG_SIZE_UP " BIG_SIZE_UP - 62 - DialogPro v 2.1 Users Guide Reference Manual BIG_SIZE_DN " BIG_SIZE_DN SCROLL_LT Scrolls virtual screen (db_ptr->handle, ______ SCROLL_LT ->handle ______ QUESTION->tile_handle) left one column. QUESTION->tile_handle SCROLL_RT " right ". SCROLL_RT SCROLL_UP " up one row. SCROLL_UP SCROLL_DN " down ". SCROLL_DN BIG_SCROLL_LT Same as above but by 8. BIG_SCROLL_LT BIG_SCROLL_RT " BIG_SCROLL_RT BIG_SCROLL_UP " BIG_SCROLL_UP BIG_SCROLL_DN " BIG_SCROLL_DN MOVE_LT Moves the window (db_ptr->handle) left one ______ MOVE_LT ->handle ______ character. MOVE_RT " right. MOVE_RT MOVE_UP " up. MOVE_UP MOVE_DN " down. MOVE_DN BIG_MOVE_LT Same as above but by 8. BIG_MOVE_LT BIG_MOVE_RT " BIG_MOVE_RT BIG_MOVE_UP " BIG_MOVE_UP BIG_MOVE_DN " BIG_MOVE_DN 2. Line Editor The line editor is invoked when editing a free_form or a reducer. Each message is translated as follows at the line editor level ________________________ (several of the messages transfer porcessing to the dialog box level--to see how messages are interpreted at the dialog box level review the previous section): CONFIRM Exits the line editor and makes CONFIRM CURRFF->response (or CURRR->response, for a ______ _____ ->response ->response ______ _____ reducer) equal to the current edited response. Also, places a CONFIRM at the tail CONFIRM of the queue. If the question is a reducer and the current response matches more than one of the specified items, the possible matches are displayed in a "pulldown" list. - 63 - DialogPro v 2.1 Users Guide Reference Manual Executes CURRFF->action(db_ptr) (or ______ ->action(db_ptr) ______ CURRR->action(db_ptr).) _____ ->action(db_ptr) _____ ABORT Exits the line editor. The current edited ABORT response is replaced by the previous response (CURRFF->response or CURRR->response.) Also ______ _____ ->response ->response ______ _____ places an ABORT at the tail of the queue. ABORT Executes CURRFF->action(db_ptr) (or ______ ->action(db_ptr) ______ CURRR->action(db_ptr).) _____ ->action(db_ptr) _____ LEFT Selects the character to the left. LEFT RIGHT " right. RIGHT HOME Selects the first character. HOME END Selects the last character. END BIG_LEFT Selects the first character in the word to BIG_LEFT the left. BIG_RIGHT Selects the first character in the word to BIG_RIGHT the right. ASCEND Same as CONFIRM. ASCEND CONFIRM DESCEND " DESCEND BACKSPACE Deletes the character to the left of the BACKSPACE cursor. DELETE Deletes the character under the cursor. DELETE MOUSE_CONFIRM Same as CONFIRM, but also puts a MOUSE_EVENT MOUSE_CONFIRM CONFIRM MOUSE_EVENT at the tail of the queue. MOUSE_EVENT Converts the last mouse event into a message MOUSE_EVENT of either POSITION or MOUSE_CONFIRM. POSITION MOUSE_CONFIRM STORE if CURRFF->insurance is NULL makes it equal ______ STORE ->insurance NULL ______ to CURRFF->response. ______ ->response ______ RESTORE If CURRFF->insurance does not equal NULL ______ RESTORE ->insurance NULL ______ makes CURRFF->response equal to ______ ->response ______ CURRFF->insurance and sets CURRFF->insurance ______ ______ ->insurance ->insurance ______ ______ to NULL. NULL FREE_STORAGE Set CURRFF->insurance to NULL. ______ FREE_STORAGE ->insurance NULL ______ POSITION Selects the character based on the value of POSITION the next integer in the event queue. - 64 - DialogPro v 2.1 Users Guide Reference Manual 3. list question Each message is translated as follows at the list level (several _________________ of the messages transfer porcessing to the dialog box level--to see how messages are interpreted at the dialog box level review the previous section): CONFIRM Executes CURRLIST->action(db_ptr), places a _________ CONFIRM >action(db_ptr) _________ CONFIRM at the tail of the queue, and exits CONFIRM back to db_run. PRESS_BUTTON check the current item on/off. PRESS_BUTTON ABORT Executes lst_freestorage, executes ABORT CURRLIST->action(db_ptr), places an ABORT at _________ >action(db_ptr) _________ the tail of the queue, and exits back to db_run. UP Highlights item above current item. UP DOWN Highlights item below current item. DOWN LEFT If in a multicolumn list selects the item to LEFT the left of the current item. RIGHT If in a multicolumn list selects the item to RIGHT the right of the current item. HOME Highlights the first item. HOME END Highlights the last item. END BIG_UP Highlights the item a window's length above. BIG_UP BIG_DOWN Highlights the item a window's length below. BIG_DOWN ASCEND Exits the list, confirms the current ASCEND responses, and executes CURRLIST->action(CURRLIST->list_ptr). _________ _________ >action( >list_ptr) _________ _________ DESCEND " DESCEND MOUSE_CONFIRM Same as ASCEND, but also puts a MOUSE_EVENT MOUSE_CONFIRM ASCEND MOUSE_EVENT at the tail of the queue. MOUSE_EVENT Converts the last mouse event into a message MOUSE_EVENT of either POSITION, POSITION_TOGGLE or POSITION POSITION_TOGGLE MOUSE_CONFIRM. MOUSE_CONFIRM STORE Stores the current selected item in another STORE data structure. RESTORE Restores the list to its state when STORE was RESTORE STORE called. - 65 - DialogPro v 2.1 Users Guide Reference Manual FREE_STORAGE Free data structures created on STORE. FREE_STORAGE STORE POSITION Highlights an item based on the value of the POSITION next instruction in the event queue. POSITION_TOGGLE Highlights item clicked on (based on the POSITION_TOGGLE value of the next instruction in the event queue,) and toggles the item on/off. POSITION_CONFIRM " POSITION_CONFIRM 4. Pull down list Pull down lists can originate from a multiple choice or a reducer question. Regardless of how they came about they operate the same. Each message is translated as follows at the pull down ________________ list level (several of the messages transfer porcessing to the __________ dialog box level--to see how messages are interpreted at the dialog box level review the previous section): CONFIRM Selects the current item as the answer, exits CONFIRM the pull down list and places a RIGHT at the RIGHT tail of the queue. Executes CURRMC->action(db_ptr) (or ______ ->action(db_ptr) ______ CURRR->action(db_ptr).) _____ ->action(db_ptr) _____ ABORT Does not change the selected item, and exits ABORT the pull down list. Executes CURRMC->action(db_ptr) (or ______ ->action(db_ptr) ______ CURRR->action(db_ptr).) _____ ->action(db_ptr) _____ UP Highlights item above current item. UP DOWN Highlights item below current item. DOWN LEFT If a multicolumn list selects the item to the LEFT left of the current item. RIGHT If a multicolumn list selects the item to the RIGHT right of the current item. HOME Highlights the first item. HOME END Highlights the last item. END BIG_UP Highlights the item a window's length above. BIG_UP BIG_DOWN Highlights the item a window's length below. BIG_DOWN - 66 - DialogPro v 2.1 Users Guide Reference Manual ASCEND Selects the current item as the answer, and ASCEND exits the pull down list. Executes CURRMC->action(db_ptr) (or ______ ->action(db_ptr) ______ CURRR->action(db_ptr).) _____ ->action(db_ptr) _____ DESCEND " DESCEND MOUSE_CONFIRM Same as ASCEND, but also puts a MOUSE_EVENT MOUSE_CONFIRM ASCEND MOUSE_EVENT at the tail of the queue. MOUSE_EVENT Converts the last mouse event into a message MOUSE_EVENT of either POSITION, POSITION_TOGGLE or POSITION POSITION_TOGGLE MOUSE_CONFIRM. MOUSE_CONFIRM STORE Stores the current selected item in another STORE data structure. RESTORE Restores the list to its state when STORE was RESTORE STORE called. FREE_STORAGE Free data structures created on STORE. FREE_STORAGE STORE POSITION Highlights an item based on the position of POSITION the last mouse event. POSITION_TOGGLE Highlights item clicked on, selects the item, POSITION_TOGGLE and exits. POSITION_CONFIRM " POSITION_CONFIRM XI. Resource Files Reference A. Introduction Resource files allow you to define a dialog box outside of the program and then pass the info to DialogPro functions to create, display or run, and destroy dialog boxes. B. Creating Resource Files 1. Introduction A resource file is a collection of dialog box definitions. A dialog box definition is a list of various records of different types. Each record begins in the first column and is terminated by a newline. For example a typical resource file definition would be: - 67 - DialogPro v 2.1 Users Guide Reference Manual ^1 "",23,71,1,0,0,7 "Program List: <None>",2,2,0,7 "Current File: untitled.c",2,3,0,7 "Warning Levels",2,5,0,7 "Output Options",19,5,0,7 "Miscellaneous",44,5,0,7 R," Level ~0",5,6,0,1 R," Level ~1",5,7,0,0 R," Level ~2",5,8,0,0 R," Level ~3",5,9,0,0 R," ~Obj",22,6,1,1 R," ~Memory",22,7,1,0 R," E~xe",22,8,1,0 R," S~yntax Check Only",22,9,1,0 C," ~Debug",47,6,0 C," ~Pointer Check",47,7,0 C," ~Stack Check",47,8,0 C," ~Language Extensions",47,9,0 C," Optimi~zations",47,10,0 F,"~Include:",2,13,12,13,58,"" F,"De~fine:",2,16,12,16,58,"" B," ~Build Program ",4,20,7181,7181,20,2 B," ~Compile File ",23,20,7181,32001,21,1 B," ~Rebuild All ",41,20,7181,32002,22,1 B," Cancel ",58,20,283,283,1,1 # 2. ID record Every dialog box in a resource file has an id number. You start a dialog box definition with a ^ in the first column followed immediately by the dialog box id, like this: ^1000 3. Window record The next line is the dialog box window record. It defines the window to display the dialog box in. This record is defined as the first line beginning with a " after the ID record. A valid window record would be: "Sample Dialog Box",23,71,1,0,0,7 Each field (separated by a comma) is: 1. The window name 2. Rows in the window - 68 - DialogPro v 2.1 Users Guide Reference Manual 3. Columns in the window 4. 0,1,or 2 for no border, a single border, or a double border. 5. 0 or 1 for "bring to the top of window stack when activated with db_run()" or "don't ... ", respectively. 6. foreground color of window's virtual screen. 7. background color of window's virtual screen. 4. Text Literal records Text Literal records begin with a ". They represent literal text to be output to the dialog box window's virtual screen when it is initially created. A valid text literal record would be: "Program List: <None>",2,2,0,7 With each field interpreted as follows: 1. The text to output. This text is output using the vs_putcodstr() conventions allowing you to change the display attributes with embedded commands. 2. X xoordinate 3. Y coordinate 4. foreground color 5. background color 5. Question records a. Introduction There are several types of question records. The order that they are listed determines the order that the user navigates the questions. b. Radio Button records These records define DialogPro radio buttons. A valid radio button record would be: R," Level ~0",5,6,0,1 The meaning of each field is: 1. Must be a capital R. Defines the record as a radio button record. 2. The radio button statement string. Note that the radio button check characters, are placed immediately to the left of the statement. If you want a space between them you should pad this string with spaces on the left. Also if you - 69 - DialogPro v 2.1 Users Guide Reference Manual want an alt-hot key assigned to the radio button put a ~ to the left of the character (must be in the range [a..z,0..9]). 3. X coordinate 4. Y coordinate 5. Radio button group. When a radio button is checked it "unchecks" all other radio buttons in its button group. 6. 0 or 1, for "checked" or "unchecked" at startup. When the dialog box is created radio button records will be setup as DialogPro rcbutton structs. c. Checkbox records Checkboxes are very similar to radio buttons except that they are not "tied" to other buttons. So checking a checkbox has no effect on other checkboxes. A valid checkbox record would be: C," ~Debug",47,6,0 The meaning of each field is: 1. Must be a capital C. Defines the record as a checkbox record. 2. The checkbox statement string. Note that the checkbox check characters, are placed immediately to the left of the statement. If you want a space between them you should pad this string with spaces on the left. Also if you want an alt-hot key assigned put a ~ to the left of the character (must be in the range [a..z,0..9]). 3. X coordinate 4. Y coordinate 5. 0 or 1, for "checked" or "unchecked" at startup. When the dialog box is created checkbox records will be setup as as DialogPro rcbutton structs. d. Free Form records Free form records allow you to gather one line text responses. A valid free form record would be: F,"~Include:",2,13,12,13,58,"" The meaning of each field is: 1. Must be a capital F. Defines the record as a free form record. - 70 - DialogPro v 2.1 Users Guide Reference Manual 2. The free form statement string. If you want an alt- hot key assigned put a ~ to the left of the character (must be in the range [a..z,0..9]). 3. statement X coordinate 4. statement Y coordinate 5. response X coordinate 6. response Y coordinate 7. response area length 8. Initial response string When the dialog box is created free form records will be setup as as DialogPro free_form structs. e. Button records Button records allow you to put info into the queue for further processing (generally some type of exit with a specified value), or execute a function. (However, buttons defined through resource files can't execute a function.) valid button record would be: B," ~Build Program ",4,20,7181,7181,20,2 The meaning of each field is: 1. Must be a capital B. Defines the record as a button record. 2. The button statement string. If you want an alt- hot key assigned put a ~ to the left of the character (must be in the range [a..z,0..9]). 3. X coordinate 4. Y coordinate 5. Keyfake value. When the button is "pressed" it will put this value into the queue. This is generally the value for the ENTER key (7181) or the ESC key (283.) These values will a. force db_run() to exit via CONFIRM or b. force db_run() to exit via ABORT (i.e. restoring all fields to their original state before exiting.) 6. Keyflicker value. When this value is processed by db_run() it will "flash" this button, put the value of Keyfake into the queue, but NOT make this the selected question. 7. If "pressing" this button results in db_run() exiting it will exit with this value if non-zero otherwise it will exit with a standard value -- i.e. CONFIRMED, ABORTED, ASCENDED, or DESCENDED. 8. 0, 1, or 2. The button will have, respectively, NO border, a single border, or a double border. When this record is interpreted by create_db() it will generate a DialogPro button struct. - 71 - DialogPro v 2.1 Users Guide Reference Manual f. List records List records create scrolling lists. A valid list record would be: L,"~List",40,1,40,3,5,15,0,1,1,"Ken","Mary","Robert","Mercedes" The meaning of each field is: 1. Must be a capital L. Defines the record as a list record. 2. The list statement string. If you want an alt- hot key assigned put a ~ to the left of the character (must be in the range [a..z,0..9]). 3. statement X coordinate 4. statement Y coordinate 5. list box X coordinate 6. list box y coordinate 7. list box viewport rows 8. list box viewport columns 9. list type -- 0 is check any, 1 is check just one. 10. maximum number of response columns. For example, a 1 would make a single long list of the selectable items, a 2 would make a 2 column list, etc. A very large number will give the effect of a list that scrolls to the right rather than down, where each column is no longer than the height the list viewport. (like the MS file selector lists in Quick C, for example.) 10. border, where 0 is none, 1 is single, and 2 is double bordered. g. Multiple Choice records Let's you define multiple choice fields in your dialog box. A valid multiple choice record would be: M,"~State",1,5,10,5,20,"Texas","New York","Maine","Massachusetts" Each field has the following meaning: 1. Must be a capital M, denoting a multiple choice record. 2. Indicates the statement portion of the field. If you want an alt-hot key assigned to this question precede the hot kye character with a ~. 3. statement X coordinate 4. statement Y coordinate 5. response X coordinate 6. response Y coordinate 7. response area length 8 .. Nth a comma delimited list of the allowable responses to the multiple choice question. - 72 - DialogPro v 2.1 Users Guide Reference Manual When this record is interpreted it will be setup as a DialogPro multi_choice struct. h. Pulldown record This record lets you specify a pull down menu. This is generally used to specify one of several pull down menus in a menu bar. Although you can include pull downs as part of any dialog box. When you make a selection from a pull down it exits the dialog box with a value of MENUED. A valid pull down record would be: P,"~Pulldown",40,15,8,"One",1,"Two",1,"-----------",2,"Three",1,"Four",1 Each field is interpreted as follows: 1. Must be a capital P, denoting a pull down record. 2. The statement portion of the pull down. 3. statement X coordinate 4. statement Y coordinate 5. The length of the active area (determines what will highlight when you select the pulldown and what area will be sensitive to the mouse.) 6 to Nth A comma delimited list of field pairs, where the first element of the pair is a list element to display in the pull down menu, and the second field indicates 1, a valid selection, 2 a title bar, 0 can't be selected. When this record is interpreted it will be setup as a DialogPro multi_choice struct. 6. Terminator record The end of a dialog box definition is signified by the terminator record. A terminator record is any line beginning with a # character. C. Testing Resource Files Having create a resource file, you must index it using idxtext.exe. idxtext will prompt you for the name of the file to index and a file name to write the index to. The resource file test program, dbtest.exe, uses the convention of giving both files the same name, with the resource file using an RSC extension and the index file an IDX extension. Since dbtest is fairly useful we recommend that you use the same naming conventions. After having indexed your resource file. You can test it by using dbtest.exe as follows. - 73 - DialogPro v 2.1 Users Guide Reference Manual dbtest <filename -- no extension> <ids to test, e.g. 32 12 1> For example, if you have create a resource file by the name of TEST.RSC and an index file with the name TEST.IDX, and you want to view dialog boxes 12 and 5. You would type the following: dbtest test 12 5 We should point out that dbtest provides very little error checking it is quit easy to create resource files which will "bomb" dbtest. D. Incorporating Resource Files into your programs To incorporate resource files into your programs you simply call the create_db() function. A typical create_db() function call would look like this: { dialog_box *db_ptr; /* create a dialog box from id 12 in the test.rsc file */ /* use the test.idx file to find the offset of id 12 */ /* in test.rsc */ db_ptr = create_db("test.rsc",0,"test.idx",0,12); /* run the dialog box */ db_run(db_ptr, 0); } To get the responses to a dialog box you need to query the structure member of the various questions comprising the dialog box. In order to do this you you must know what DialogPro structures are created based on the resource file records. This information is contained in the previous section on Question Records. For example, this dialog box definition is comprised of : ^1 "",23,71,1,0,0,7 "Program List: <None>",2,2,0,7 "Current File: untitled.c",2,3,0,7 "Warning Levels",2,5,0,7 "Output Options",19,5,0,7 "Miscellaneous",44,5,0,7 -- question 0 -- R," Level ~0",5,6,0,1 -- question 1 -- R," Level ~1",5,7,0,0 - 74 - DialogPro v 2.1 Users Guide Reference Manual -- question 2 -- R," Level ~2",5,8,0,0 -- question 3 -- R," Level ~3",5,9,0,0 R," ~Obj",22,6,1,1 R," ~Memory",22,7,1,0 R," E~xe",22,8,1,0 R," S~yntax Check Only",22,9,1,0 C," ~Debug",47,6,0 C," ~Pointer Check",47,7,0 C," ~Stack Check",47,8,0 C," ~Language Extensions",47,9,0 C," Optimi~zations",47,10,0 -- question 13 -- F,"~Include:",2,13,12,13,58,"" F,"De~fine:",2,16,12,16,58,"" B," ~Build Program ",4,20,7181,7181,20,2 B," ~Compile File ",23,20,7181,32001,21,1 B," ~Rebuild All ",41,20,7181,32002,22,1 B," Cancel ",58,20,283,283,1,1 # If having created this dialog box, and run the dialog box, you could query the dialog box structures to determine the users responses. For example, since question 0 is a radio button, we know that this is setup as an rcbutton struct, and we know that the rcbutton struct member, checked, indicates if the radio button was checked when we exited. Therefore, we can get the user's response to this radio button as: ((rcbutton *)(db_ptr->questions[0]))->checked Alternatively you could use the #defines in dbpro.h to simplify this to: RCBUTTONQUEST(0)->checked likewise to get the users response to the free form question 13 you would use: ((free_form *)(db_ptr->questions[13]))->response or FFQUEST(13)->response Once you have gotten the info you need from the dialog box you can release it from memory with a call to destory_db() like this: - 75 - DialogPro v 2.1 Users Guide Reference Manual destroy_db(db_ptr) One important caveat to remember when using destroy_db() is that the assumption is made that the response to the free form questions have been captured by assigning them to some other variable before the destroy_db(), and therefore the memory allocated to the free form response is not released. If you want to release all of the memory associated with a dialog box you must free() all the free_form.response members. E. Embedding Resource Files In the previous section we demonstrated how to use db_create() to access a resource file and display a dialog box. In that section we said to ignore the 0's after the resource file and index file names in the call to create_db(). These values represent the offset into a file where the index info and or the resource info is found. These parameters allow you to combine the resource and index files with other files, your exe file for example. To illustrate. Suppose you create an exe file called dbbound.exe, a resource file called test.rsc, and a resource index file called test.idx. Let's say that their respective file sizes are: dbbound.exe 131,012 test.idx 100 test.rsc 3,456 if you were to copy these files into a single file using the DOS copy command like this: copy /b dbbound.exe+test.idx+test.rsc dbbound1.exe the index information would be found at an offset of 131,012 in dbbound1.exe, and the resource file information would be located at an offset of 131,112 in dbbound1.exe. With this information in hand you could edit the original dbbound.exe source as follows: main(argv,argc) int argv; char argc[]; { dialog_box *db_ptr; init_dbpro(); /* create a dialog box from resource file info found at */ /* an offset of 131112 of the exe file (argc[0]), and the */ /* index file info found at an offset of 131,012 in the */ /* exe file -- use dialog box id #1 to create db */ - 76 - DialogPro v 2.1 Users Guide Reference Manual db_ptr = create_db(argc[0],131112L,argc[0],131012L,1); /* display the dialog box */ return(db_run(db_ptr,0)); } and recompile (this should have no effect on the original executable size). Then combine the files as indicate above, and run. The three files can now be distributed as a single file, dbbound1.exe. F. Functions 1. create_db a. Summary #include "dbpro.h" #include "dbpro.h" #include "dbbuild.h" #include "dbbuild.h" dialog_box *create_db(resource, roffset, index, ioffset, id) _____________________________________ dialog_box *create_db( ) _____________________________________ int resource; _________ int _________ unsigned long roffset; ________ unsigned long ________ int index; ______ int ______ unsigned long ioffset; ________ unsigned long ________ unsigned id; ___ unsigned ___ b. Description The function create_db() create a dialog box from the resource create_db info contained in the file ( a file handle), resource, starting ________ at the offset roffset in the file. It uses the the index info _______ contained in the file (a file handle), index, starting at the _____ offset, ioffset, to locate the particular dialog box to create, _______ id. __ c. Return Value Returns a NULL if it was unable to create the dialog box, otherwise returns a pointer to a dialog_box struct. 2. destroy_db a. SUMMARY #include "dbpro.h" #include "dbpro.h" #include "dbbuild.h" #include "dbbuild.h" void destroy_db(db_ptr) ______ void destroy_db( ) ______ - 77 - DialogPro v 2.1 Users Guide Reference Manual dialog_box db_ptr; ______ dialog_box ; ______ b. Description The function destroy_db() frees the memory allocated to a dialog destroy_db box via a call to create_db(). With one exception. create_db free_form.response is not freed, as we assume that the dialog box responses are used in some manner for further processing. c. Return Value None. XII. HypeIt! HypeIt! is a hypertext like help system. Run the program hypeit.exe for further information on HypeIt!. - 78 - ----------------- The DialogPro registration form --------------- Mailing Address Name :___________________________________________________ Company Name :___________________________________________________ Position :___________________________________________________ Street :___________________________________________________ ___________________________________________________ City :_________________ State :__ Zip Code :__________ Country :___________________________________________________ Compuserve # :_________________ Phone # : ______________________ Computer System Manufacturer :___________________________________________________ Model :___________________________________________________ RAM :___________________________________________________ Disk Media 5 1/4" 360K __ 5 1/4" 1.2mb __ 3 1/2" 720K __ 3 1/2" 1.4mb __ Hard Disk Capacity :___________________________________________________ Video Adapter:___________________________________________________ Monitor :___________________________________________________ How did you hear about DialogPro? ______________________________ _________________________________________________________________ _________________________________________________________________ _________________________________________________________________ Desired Support Level (check one) __ $15, The DialogPro shareware diskette __ $50, registered DialogPro shareware library user __ $100, registered DialogPro source code user (non-commercial) __ $200, registered DialogPro source code user (commercial) Include a check for the amount corresponding to the desired level of service. Make the check payable to, Seabreeze Software.